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CROMEMCO MACRO ASSEMBLER 


CHAPTER 1: 

GETTING STARTED IN ASSEMBLY LANGUAGE PROGRAMMING 


The purpose of an Assembler is to provide a 
means of translating easily understood mnemonics, 
which represent the instructions of a computer, 
into object code which may be loaded into memory 
and run as a program. The CROMEMCO Disk-Resident 
Z-80 Relocatable Macro Assembler is a two pass 
assembler which reads source code from a disk file, 
assembles it, and produces a relocatable object 
and/or a print-listing file. These files may be 
sent to any of the disks, suppressed altogether, or 
sent to the console (listing file only). The 
CROMEMCO Relocating Linker/ Loader may then be used 
to locate the assembled code anywhere in memory. 
The completely assembled and linked machine code 
may be saved in a disk .COM file for execution as a 
command program. 


The use of a relocatable assembler and linker 
provides one of the most versatile ways of creating 
machine language programs for the computer. The 
time saved through their use is well-worth the time 
spent in gaining familiarity. These two command 
files allow one to create and assemble a number of 
different modules separately, and then link them 
together at run time. Or one can link an assembled 
user-program to an already existing library of 
useful object code files. In addition one may 
assemble programs using a compiler (for example, 
assemble FORTRAN programs into machine code using 
CROMEMCO’s FORTRAN Compiler), and link these object 
modules to existing machine code modules, programs, 
or subroutines. At the same time the final program 
may be located to run anywhere in memory. 


The CROMEMCO Relocatable 
called ASMB or the Assembler) 
Conditional Assembler as well 
of this manual is devoted to 
Macro capability allows the 
generate such things as multiple 
design added capabilities for the 
particular purpose, and write 
versions of source code by having 
searched for often-used routines. 


Assembler (hereafter 
is both a Macro and a 
. A separate chapter 
these features. The 
user to very easily 
blocks of code. 
Assembler for a 
much shortened 
a Macro library 
The Conditional 
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{ IF statement) assembly feature al lows blocks of 
code to either be included or not, depending on the 
satisfaction of user-defined conditions. There are 
also capabilities for INCLUDing other source code 
files at assembly time and declaring other program 
modules EXTernal to the main pr ogr am , which are 
then linked to it at run-time. All these features 
are described further in the chapters on pseudo- 
ops. 

The CROMEMCO Relocatable Macro Assembler is 
supplied to the user on diskette (large or small) 
under the directory entry "ASMB.COM". The way the 
Assembler is called is described in detail in 
Chapter 2. A source code file to be assembled must 
have the three-letter extension .Z80 to be found by 
ASMB. To assure correct operation the Assembler 
should be used with the following minimum hardware 
configuration: 32K of contiguous RAM memory 

beginning at location 0 and the CROMEMCO 4MHz Z-80 
CPU card, along with the CROMEMCO Disk Operating 
System (CDOS) hardware and software. When called, 
ASMB loads into memory at 100H and begins execution 
there . 

Since most users will be eager to try out some 
of the features of ASMB right away, this chapter 
may be used as a step-by-step beginner's manual for 
the composition, assembly, link, and execution of a 
simple Z-80 machine language program. The name of 
the program is "TIMER" and its pur pose is to ring 
the console bell at approximately halfsecond (using 
4MHz clock) intervals as determined by a timer 
loop. It will not be necessary for those users 
familiar with assembly language programming to read 
this chapter. These persons may skip ahead to 
Chapter 2 at this point. 

The first step is to turn on the power to the 
computer and boot-up the CROMEMCO Assembler Disk 
(Model FDA) in drive-A. You will notice upon 
typing out the directory that sup pi I ed along with 
the Assembler (ASMB.COM) is the CROMEMCO Text 
Editor (EDIT.COM) and CROMEMCO Debug (DEBUG.COM) 
programs. We will use the Text Editor to enter our 
source code program. The Editor manual is also 
s uppl i ed with the Assembl er packag e and sho uld be 
used for questions and reference concerning EDIT. 
However, some of the simple commands are explained 
here for the benefit of the user who is unfamiliar 
wi th the Ed i to r . 
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The user can now call EDIT giving the name and 
three-letter extension of the file we wish to 
create by typing the following. (Note that before 
typing the command line you should have the CDOS 
prompt for the drive you are using, for example 
"A." for drive -A.) 

EDIT TIMER. Z80 

The Editor will then res pond with: 

CDOS EDITOR VERS. xx. yy 

NEW FILE 

The prompt for the Editor is an asterisk, "*", 
and commands may be entered any time this prompt is 
d i splayed . We now wish to enter the text of the 
source program so we use the Insert command of 
EDIT. This is done simply by typing the letter "I" 
followed by a carriage return (CR) . We can then 
start typing lines of text, ending each line with a 
carriage return. Mistakes can be corrected by 
backspacing or can be corrected after we have 
finished with Insert mode as explained below. 
There are four fields which may be used in a line 
of source code: labels, opcodes, operands, and 
remarks. Labels are followed by a colon and 
remarks are preceded by a semi-colon. If there are 
more than one operand, they are separated by a 
comma . The instruction mn emon i cs or opcodes fo r 
the various Z-80 instructions can be found in the 
Z-8 0 CPU Technical Manual published by Mostek and 
Zilog along with an explanation of each. Note that 
in the following text a tab was used to separate 
the various fields; this is done in the Editor by 
typing the CTRL-I on the console. Also note that 
either upper-or lower-case are allowed. We now 
type in the source code: 
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This program rings the console bell at approximately 
half-second intervals determined by a timer loop. 


BELL: 

EQU 

7 ; 

console bell is ASCII 07 

WRITE: 

EQU 

2 j 

write character to console 

CDOS : 

EQU 

5 ; 

use system call to write 

TIMIT: 

EQU 

2FFH ; 

2 is no . of half-seconds; 

t 



FF (256) is no. of loops 

DURAT: 

EQU 

0FFH 

FF (256) is loop duration 

; Main 

Prog ram 



START: 

LD 

SP, STACK 

initialize stack pointer 

LOOP: 

LD 

BC, TIMIT 

B is no. of half-sec.; 

f 



C is no. of loops 

TIM2 : 

LD 

A, DURAT 

get duration (256) 

TIM 1 : 

DEC 

A 

decrement and 


JR 

NZ , TIM1 

loop til zero 


DEC 

C 

decrement loop counter 


JR 

NZ , TIM2 

until zero 


DJNZ 

TIM2 

countdown ha If- seconds 


LD 

E, BELL 

set-up to ring bell 


LD 

C, WRITE 

set-up to write console 


CALL 

CDOS 

call system 


JP 

LOOP 

loop and repeat 

i 

; Stack 

Area 



BOTTOM: 

DS 

40H ; 

; allow 64 bytes for stack 

STACK: 

EQU 

$ i 

; current location counter 




equals top of stack 


END 

START 



This code should be typed in exactly as it 
appears here (although comments may be omitted if 
desired). When the entire body of text has been 
entered, end the Insert mode by pressing ESCape or 
CTRL-Z. (You have left Insert mode when you again 
get the asterisk prompt.) You now would like to 
review what you have written to check for errors. 
Move the character-po inter to the top of the file 
by typing " B <CR>". Then type out your file using 
the T or P command. For example the command 10T 
will type out 10 lines, or 0P will type out the 
current page of 23 lines. The S or Substitute 
command can now be used to make corrections. The 
format of the command is: 
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where the " " [ " character is an ESCape. The text 
string for which you are substituting must be 
exclusive; for example the command 

SP" [R“ [ 

is not good because the first " P" encountered will 
be changed to an "R". The following command is 
much better because the substitution is for a one 
of a kind string: 

S JP "INZ , TIM1 ~ [ JR'INZ , TIM1 " [ 

The "''I" is the way EDIT prints CTRL-I’s. When all 
corrections have been made, you may Exit from the 
Editor by typing "E <CR>". When the "A." prompt 
is again displayed on the console, the created file 
will have been saved on the disk under the filename 
"TIMER. Z80 " . If you desire more information about 
editing files at this point, refer to the Text 
Editor Manual for complete descriptions of the 
Editor commands. We will now proceed with 
assembling the file. 

The Assembler is called in a similar manner to 
the Editor. The command line you sho uld type is: 

ASMB TIMER 

The Assembler understand s when it receives this 
command line that it will find the source file on 
the current drive, and that it will place the ,REL 
(relocatable) object file and . PRN (print) listing 
file on the current drive as well. Our file 
"TIMER. Z80" will now be assembled. When finished, 
control will again be returned to CDOS and the "A." 
prompt given. Just prior to exiting, ASMB will 
print on the console: 

Errors 0 

Program Length 005A (90) 

end of assembly 

provided you have made no typing errors in editing 
the file. If there are some errors, re-edit the 
file and correct them as described above. Then re- 
assemble as before. The numbers above give the 
program length first in hexadecimal and then 
decimal . 
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The Assembler will now have created the .REL 
and , PRN files on the disk. If you would like a 
listing of the prog ram , type : 

TYPE TIMER. PRN 

and press CTRL-P (assuming you have a printer 
correctly hooked up to parallel port 54H; if you 
have no printer, omit the CTRL-P) before typing the 
carriage return. The listing will then be printed 
on both the console and the printer. There is a 
great deal of information contained in this 
listing. Briefly, the listing consists of these 
sections. The first column is the hexadecimal 
address of the instruction, and the second column 
may be one of three things: (1) the object code of 
up to a four-byte instruction in hex, (2) the 
object code of four bytes of data in hex, or (3) 
the equivalent value of the operand expression in 
parentheses. The third column gives the line 
numbers of the source in decimal. The fourth, 
fifth, and sixth columns are the label, opcode, and 
operand fields, respectively. 

The rest of each line contains the remark if 
there is one. The complete listing which results 
from the assembly of our given example source file 
is given in Chapter 7 along with a detailed 
description of every feature of the listing. 

The last step prior to running the prog ram is 
to load it into memory. This is done using the 
CROMEMCO Linker/Loader . The command line that 
should be typed is : 

LINK TIMER 

The Linker will then prompt with an asterisk 
(*). This means that it is awaiting further 
instructions. At this point you may either start 
execution or exit to CDOS, save the file, and 
execute it as a command file. Let us choose the 
second method. (For those who wish to try the 
first method, simply type /G to the prompt.) 

To the asterisk type the characters /E which will 
exit to CDOS. LINK will then print on the console 
a message similar to: 

[1000 1 05A 16] 

The first number is the starting address for 
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execution, the second number is one more than the 
highest address used by our program, and the last 
number gives the number of pages to be saved to 
create a command file. We now create this .COM 
file by typing : 

SAVE TIMER.COM 16 

Command files may be executed directly from 
CDOS simply by typing their name. They are then 
loaded into memory beginning at 100H and execution 
begins there. The Linker has already placed the 
necessary "JP 1000H" for us at 100H so we execute 
the TIMER program simply by typing the word 
"TIMER 1 '. The bell on your console should begin 
ringing at approximately half-second intervals, 
telling you that the machine language program we 
have created is working! 

Good assembly language programming practice 
usually dictates that a program should be debugged 
before executing it directly as we have done. By 
this method the user can insert breakpoints to stop 
execution so that the registers and memory contents 
can be checked to determine if the program is 
executing correctly. We have skipped the debugging 
stage so as not to complicate the example 
unnecessarily. However, when you create assembly 
language programs of your own, you can use the 
CROMEMCO Debugger program (DEBUG.COM) to execute it 
using breakpoints. To do this you would first have 
to save your program in a file as we have done 
above; then load it using DEBUG. See Part III on 
the Debugger for several examples of the way to 
d ebug a program . 

The example program of this chapter is KNOWN 
TO WORK if the source is created and assembled 
according to the procedures outlined above. Should 
you have any difficulties with any of the steps, 
try working through that step a second time. You 
may also refer to the manual which describes that 
function for a detailed description of the 
procedure. This book is divided into a number of 
distinct parts, which are listed in the table of 
contents for reference. Parts I, II, and III are 
the complete Assembler, Link, and Debug manuals, 
respectively. Part IV is the CDOS Programme r 1 s 
Manual, describing the many system calls which can 
be made to CDOS for I/O and disk operations. Part 
Visa description of the Library of relocatable 
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modules which are supplied with the Assembler disk. 
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CHAPTER 2: CALLING THE ASSEMBLER 


The Assembler is called from disk simply by 
typing "ASMB" followed by the filename of the 
source code to be assembled. This sourcefile MUST 
have the extension .Z80 to be found by the 
Assembler, regardless of whether or not it consists 
entirely of Z80 code. However, when calling ASMB, 
the user may specify an optional 3-letter drive- 
request for the filename which has NO relation to 
the 3-letter extension of the filename on disk. 
Note that if this 3-letter drive instruction is 
omitted, ASMB will default to the CURRENT drive for 
all operations. This drive-request instruction is 
of the form .QRS, where Q stands for one of the 
letters, A, B, C, or D, and is the drive on which 
the SOURCE file is to be found; R stands for one of 
the letters, A, B, C, D, or Z, and is the drive on 
which the relocatable OBJECT file is to be placed 
during assembly (Z means do not create an object 
file); and S stands for one of the letters. A, B, 
C, D, X, Y, or Z, and is the drive on which the 
pr in t- 1 i st ing will be placed during assembly. In 
the case of the print-listing Z means do not create 
the listing, Y means send the listing to the 
printer, and X means send the listing to the 
console but not to the disk. Error messages will 
as always be sent to the console if the Y 
instruction is used. The Y instruction will start 
and stop the printer at the correct times provided 
the printer is turned on and selected before 
assembly. This instruction has been provided for 
those users having teletypes who would not wish to 
have a listing sent to both the console and the 
printer simultaneously. Note that you may use the 
Control-P ( ~P} function of CDOS, as always, to 
cause the console listings to also be sent to a 
printer. Also note that the relocatable object 
file will be placed on the disk with the extension, 
.REL, and the print-listing will be placed with the 
. PRN extension . 

An example will serve to illustrate further 
the features described above. Suppose the file to 
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be assembled resides on disk drive A under the 
filename USERFI LE . Z8 0 . If it is desired not to 
have the .REL and .PRN files sent to drive A (for 
lack of room on disk A, for example) , the Assembler 
might be called by the command line: 

A SMB USERFI LE. ABX <"P> <CR> 


This will assemble the source file on 
create an object file on drive B , and 
print-listing to both the console and the 


drive A, 
send the 
printer. 


A number of options may also be specified at 
assembly time if desired; their conventions are 
described in detail in the following sections. 
These options are specified simply by typing them 
as part of the command line when calling ASMS, 
separated by spaces. Since there are quite a 
number of options, it's possible to have the 
command line exceed the 1 i ne-leng th limit of the 
terminal being used. If this is the case, a 
Control-E (~E) may be issued to provide a physical 
CR-LF so that the command line may be continued. 
Note that a logical CR-LF {same as typing RETURN on 
the console) terminates the c ommand and begins 
assembly. If the terminal being used automatically 
provides a logical CR-LF at the physical end of a 
line, then a Control-E should be issued before the 
end-of-line has been reached. The total line 
length is limited to 128 characters by CDOS. 


Options are specified only in the call to 
A SMB. The only exceptions to this are the List 
Options (see below), which may be used in slightly 
different form as operands of the LIST pseudo-op. 
Options may be specified in any order; any number 
of the allowable options may be specified at the 
same time. Consider the following sample call of 
the file THISFILE.Z80 by ASMB: 


A SMB THISFILE RANGE PAGE=50 SYMB XREF OPCODE 


Notice that the 3-letter drive-request instruction 
was not used in this example; this means that all 
disk operations will involve the current drive. 
The options specified ask ASMB to mark relative 
jumps, format a listing page, and generate symbol 
and cross reference tables. These are described in 
more detail below under the respective options. 

Throughout this manual, the symbols "< >" are 
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used to bracket quantities which are to be replaced 
by user-quantities, usually names of files on the 
disk. However, in NO cases are the bracket symbols 
themselves to be entered with the quantity 
involved. Also, throughout this manual, the 
pseudo-ops are written in all-upper-case to set 
them off. However, this does not mean that they 
must be written this way in source-code. Both 
upper-and lower-case are acceptable. 


Options Specified When Calling ASMB 


List Options 

The List Options are similar to the operands 
of the LIST pseudo-op which may be part of a source 
file. However, the List Options as specified at 
assembly time will override ANY and ALL LIST items 
given in source code. Following are the four 
allowable List Options; they are specified by 
typing the word(s) given here in the command line 
calling ASMB. Note that if mistakenly both of a 
pair Cond-Nocond or Gen-Nogen are specified, the 
one which appears last on the command line has 
precedence. An important point to note is that 
NONE of the List Options changes the actual object 
code assembled; they merely change what is sent to 
the print-listing file on console or disk. 


Cond 

This option forces the generation and printing 
of all blocks of code which are part of an IF 
definition, whether the IF is true or false. The 
default is Cond if no LIST pseudo-ops are present 
in the source file; therefore, it would generally 
be used as an option only to override all the 
Nocond operands of LIST in the source. Note that 
this has NO effect on whether the IFs are satisfied 
or not . 
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Gen 

This option forces the generation and printing 
of the Macro which follows every Macro call. The 
default is Gen if no LIST pseudo-ops are present in 
the source file; therefore, it would generally be 
used as an option only to override all the Nogen 
operands of LIST in the source. 


HEX and HEX= 

The program LINK.COM supplied with this 
ASSEMBLER package has the advantage of being able 
to link in any order and load into memory a number 
of relocatable modules. However, it has the 
disadvantage that the final linked machine code 
will be loaded beginning at the address 100H. The 
Linker puts a jump instruction at 100H so that if 

the program is saved as a command file (.COM) , it 

will still execute correctly from that location. 
(Note that LINK locates any DATA areas BEFORE the 
program and beginning at 100H; thus, program 
execution may start at an address above 100H.) 
This disadvantage of LINK may be partially 
circumvented by assembling the source code as 
ABSol ute code which has been ORGed at an address in 
memory at or above 100H; however, in this case the 
program will no longer be in RELocatable format and 

can thus not be linked to other modules. 

For those users who wish to forgo 
r el ocatabi 1 ity and would prefer instead to create 
absolute code which may be ORGed anywhere in 
memory, a non-relocating option for ASMB is now 
included. This is the HEX or HEX= option, and is 
specified when calling the Assembler. This section 
is therefore in addition to Part I, Chapter 2, 
Section 1 of the Assembler Instruction Manual 
describing such options. The HEX option is given 
on the command line which specifies a program to be 
assembled, and informs the Assembler to create a 
.HEX output file INSTEAD OF a .REL (relocatable) 
output file. This means that ASMB outputs the 
object code to a file on the disk having the same 
filename as that being assembled, but with the .HEX 
extension. The object code is written to the disk 
file in Intel hex format. Thus, it can NOT be 
loaded into memory using LINK; rather the CROMEMCO 
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Debugger program will load a hex-format object file 
into memory prov ided it has the extension .HEX. 
{Files having any other extension are loaded by 
DEBUG exactly as they are stored on the disk.) 

The HEX= option is really an extension of the 
HEX option described. It also causes the 
generation of a .HEX output file; however, the 
output file will be ORGed at the hex address 
specified immediately following the "=" sign of the 
option. The source program will remain so ORGed 
ONLY until it encounters the first ORG pseudo-op of 
the source program; that is to say, the ORG 
statements of the source over ride the HEX= option . 
However, there are advantages to be gained by 
leaving any absolute ORG or ABS statements out of a 
program, and then specifying the run address using 
the HEX= option. For example, a program which is 
eventually to run out of ROM can be d eveloped on 
the same system in RAM by first assembling with a 
RAM address, then working out any bugs, and finally 
re-assembling with the correct run address for ROM. 


Nocond 

This option forces NO printing of IF or ENDIF 
statements and NO printing of IF definitions (the 
code following the IF) if the IF statement is 
false. In other words if the IF statement equals 
0, thus causing the code which is part of the IF 
not to be assembled, the pr i n t- 1 i s t i ng will 
likewise not contain the unused IF code. If the IF 
statement has a value other than 0 and is thus 
true, the pr int- 1 i sting will not contain the IF or 
ENDIF lines but will contain the code of the IF 
definition; therefore, the included portion of code 
will appear contiguously with the rest of the 
source code. The Nocond option is used to override 
all the Cond operands of LIST pseudo-ops in the 
source file. 


Nogen 

This option forces NO printing of the code 
following MACRO calls. However, NOTE that Macro 
DEFINITIONS are always printed as are the Macro 
CALLS themselves; it is only the code which the 
Macros generate, the Macro Expansions, which are 
not printed. This option prevents very long print- 
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listings when using multiple Macro calls. Since 
the Macro code will not be printed, neither will 
the object code which is printed on the same line; 
however, Nogen does not in any way affect the 
object code sent to the .REL file. The Nogen 
option is used to override all the Gen operands of 
LIST pseudo-ops in the source file. 


Macro=<d : filename . ext> 

The Macro= option is one of the most powerful 
features of the Assembler. It is used to specify 
the name of a disk file which is to be searched to 
satisfy any Macros required at assembly time. 
During Pass 1, the Assembler forms a Macro 
Definition Table (MDT) of the Macros defined in a 
source program. (Remember that ASMB expects Macros 
to be defined before they are called.) If the 
Macro® option is specified, a table is formed of 
the ADDRESSES of the Macros contained in this 
library. Now, when an opcode is encountered in a 
source program, the MDT is the first place searched 
to satisfy it. If it is not found there, the Macro 
Address Table for the Macro Library (only when 
using Macro®) is searched next; if the Macro is 
found, then the Macro Definition is loaded into 
memory from the disk. If the opcode is not found 
in either of these places, the Opcode Definition 
Table ( ODT ) is searched last. Thus, because ASMB 
searches for a Macro before an opcode, it is 
possible to redefine 2-80 instructions using Macros 
(see the chapter on Macros). Another advantage of 
this method of searching is that the entire Macro 
Library specified does not become part of the 
source code. Thus, you may specify a very large 
Macro-library file, but only those Macros actually 
used are included in the assembled code. Note that 
this is different from the INCLUDE pseudo-op in 
that the INCLUDE would include the entire file, 
needed or not . 

The Macro® command should be typed exactly as 
shown above, where the user would insert following 
the " = ", the filename. ext to be searched. The "d:" 
represents the disk drive letter (one of A-D) and 
is optional; if not specified, ASMB defaults to the 
current drive in its search for the Macro file. 
The default for the Macro® option is, of course, no 
Macro file searched; however, this does not in any 
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way affect the manner in which Macros intrinsic to 
the source code are handled. 


Opcode 

The Opcode option, when specified, will create 
a cross reference listing of OPCODES and MACROS 
used, which will be sent to the console or disk 
following the ass embl ed-cod e listing. This cross 
reference contains all of the opcodes used in the 
assembled program along with the Macro names used, 
in alphabetical order, and the line numbers of 
their definitions and places of occurrence. The 
first column following the column of opcodes and 
labels is reserved for the line numbers of the 
definition points of Macros, and is thus blank for 
the opcodes. Subsequent entries contain the line 
numbers of the places of occurrence of opcodes and 
Macros. Note that opcode cross reference listings 
are limited in width by the Width option. A line 
will be stopped at the last complete entry which 
will fit the specified width and will be continued 
on the next line. The Opcode option is very useful 
for debugging purposes as it allows you to find all 
the occurrences of a particular opcode very 
quickly. The default is no-Opcode cross reference 
table . 

The Opcode Cross Reference is implemented by a 
disk sort. This means that when this option is 
selected, ASMB creates a file on the CURRENT drive 
called <f ilename> .$$0 where filename is the file 
being assembled. Then, when assembly and the 
opcode cross reference are complete, this file is 
deleted from the disk. Note that if the current 
drive does not have room for the opcode temporary 
file, an error message is printed and assembly is 
aborted (see also "write error" in the error 
message chapter). 


Page=<number decimal lines/page> 

The Page option is used when generating a 
printer-listing to cause the Assembler to calculate 
and display a specified number of lines per page. 
At the top of each page ASMB will also print a 
heading, a title if specified, and a page number. 
Note that even if several lines are longer than the 
Width specification and wrap around, the Page 
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function will count these correctly, and will list 
the exact number of lines specified per page 
(including the heading). The default value is 60 
and the limits are 10 to 254 lines. Note that the 
Page=, Top=, and Width= options must be typed 
exactly as shown (no spaces) in order to be 
interpreted correctly. 


Parity 

The Parity option is normally specified when 
assembling code which was originally 8080 code and 
has been entered using 280 mnemonics. This is 
because the Z80 and 8080 microprocessors treat the 
parity flag slightly differently and the Z80 may 
not execute 8080 parity instructions correctly (the 
Z80 treats parity as an overflow flag after 
arithmetic instructions) . By specifying the Parity 
option, the user will be warned in the assembled 

listing of possible problems along this line by the 
letter 'P' preceding the line numbers of the 

affected lines. It is up to the user to determine 
whether or not the parity flag is used correctly in 
a given situation. The instructions which will be 
marked are: JP PE,nn; JP PO,nn; CALL PE,nn; CALL 

PO,nn; RET PE; and RET PO. The default is no- 

Par ity . 


Range 


The Range option is used to have the Assembler 
tell you all those places in code which currently 
use absolute jumps which are "within range" for 
doing relative jumps. When specified, the line 
numbers of the affected jumps will be preceded by 
the character "R". Thus, the next time the code is 
edited for changes, the corresponding absolute 
jumps may be replaced by relative jumps. Note that 
the Assembler itself does NOT make the 
replacements. The default is no-Range option. 


Symbol o r Symb 

The Symbol option is used to cause the 
Assembler to print the symbol table following the 
listing. The symbol table lists all program or 
data label names in alphabetical order from left to 
right in rows, and the hex address which is the 
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value of the label used by the Assembler followed 
by the type of code segment there. For example the 
entry: 


LABEL 0 0A7 1 

means that LABEL has the value 00A7 in the 

r elat i ve-code program area. (The symbols #, *, " , 
and 1 are defined in the section on code segments.) 
If the label belongs to an EXTernal , the address 

given is that of its last OCCURRENCE in the present 

module, rather than its actual value. Similarly, 
for a label defined by a DL (see Define Label), the 
value listed in the symbol table is its last value 
to occur in the source code. The Width of the 

symbol table in a printer listing will be the same 
as that of the code listing preceding it; however, 
the line length of the symbol table will be limited 
to include the last full label name and address 
which can be fit within that width. The default is 
no-Symb table option. 


Top=<no. dec. lines before top> 

The Top option is used to specify the number 
of lines between the last line of one page and the 
top or first line of the next page when creating 
printer listings. This feature may be used to 
specify the spacing between pages when creating 
listings. If the value 0 is specified, formfeeds 
are issued to the printer at the end of each page. 
This is the default value and is the one ordinarily 
used. Notice that the values of Page+Top should 
equal the number of lines desired per page of 
printed text. The limits are 0 to 255 lines. 


Width=<number decimal column s> 

The Width option is used to specify the number 
of characters of printed text which will appear per 
line of a listing. This feature is used to allow 
the use of different widths of paper in printer 
listings or to allow for terminals capable of 
displaying different numbers of characters per 
line. The default value is 79, which should 
accommodate all 80-character terminals. The limits 
are 39 to 255 characters. If lines longer than 
that specified are written, they will wrap around 
and be continued on the next line of the listing. 
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Note that the symbol table, error listing, and 
opcode and label cross reference tables are also 
limited by the Width specification* 


Xr ef 


The Xref option, when specified, will create a 
cross reference listing which will be sent to the 
console, printer, or disk (as specified) following 
the assembled-code listing. This cross reference 
contains each of the label names used in the 
assembled program, the line number of its 

definition, and the line numbers in numerical order 
of each of its places of occurrence. The first 
column following the column of labels is the column 
of line numbers of their definitions. Note that if 
DL 1 s (Define Labels) are used in the source code, 
those label names may be defined more than once. 
Thus, in the cross reference listing, the 

subsequent defining line numbers are preceded by a 
1 # 1 to set them off. Do NOT confuse this with the 
' # 1 for Data areas defined elsewhere. The ENTRY 
pseudo-op will also generate a doubly defined 
label, once at the ENTRY point itself and once 

where the label is actually defined. The Xref 

option is very useful for debugging purposes as it 
provides an alphabetical listing of the locations 
of every label used in a program. The default is 
no-Xref table. Note that cross reference listings 
are limited in width by the Width option and that a 
line will be limited to the last complete entry 
which will fit within that specification; entries 
will then be continued on succeeding lines* 

The Xref Cross Reference is implemented by a 
disk sort. This means that when this option is 
selected, ASMS creates a file on the CURRENT drive 
called < f il ename> . $$$ where filename is the file 
being assembled. Then, when assembly and the cross 
reference are complete, this file is deleted from 
the disk* Note that if the current drive does not 
have room for the cross reference temporary file, 
an error message is printed and assembly is aborted 
{see also "write error" in Chapter 6) , 


26 



CROMEMCO MACRO ASSEMBLER 


Summary of Def a ul t s and Limits 


The default values and limits of the above 
options are summarized here for convenient 
reference . 


Defaults 

In the absence of specified options, ASMB will 
default to these values: no-Range, no-Parity, no- 

Xr ef f no-Symb , no Mac ro= , no-Qpcod e , Pag e=6 0 lines, 
Top=0 (formfeed), Width-79 characters, default to 
List options specified within source code as 
operands of the LIST pseudo-op. 


Limits 

The paper-managing options for generating 
printer listings are limited to the following 
values: Page= 10 through 254 lines. To p= 0 

(formfeed) through 255 lines, Width= 39 to 255 
characters. The lower limits on Page and Width are 
imposed to assure that at least some code is 
pr in ted on each page. 
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CHAPTER 3: ASSEMBLER FIELDS 


The Assembler recognizes four fields or 
different types of expressions. These are: 
labels, opcode mnemonics, operands, and remarks. 
The conventions which apply in the use of these 
four fields are given below following remarks on 
the syntax of ASMB. Any two of the four fields 
must be separated from each other by at least one 
delimiter; these are: a tab, a space, a colon 

(after labels only), a semi-colon (before remarks 
only), or a CR-LF (to terminate lines). Multiple 
delimiters may be used to improve readability. 


Characters and Line Length 

The Assembler accepts any printable ASCII 
characters in lines of code. Specifically, this 
means any ASCII character having a hex value 
between 20H and 7EH inclusive. In addition the 
three control characters, CTRL-I, CTRL-N, and CR 
are also recognized ("I is the tab character which 
is translated into up to eight spaces by ASMB, "N 
is the character to expand a line on the printer, 
and CR is a carriage return). NO other control- 
characters are recognized by ASMB. The maximum 
length of a line accepted by the Assembler is 80 
characters, where the last character is the CR. 
Lines having more than 80 characters will be 
tr unca ted . 


Upper and Lower Case 

It would be good to mention at this point that 
the Assembler will accept ALL commands, options, 
opcodes, pseudo-ops, filenames, or any of the other 
Input it requires in both upper and lower case or a 
combination of the two. This means that source 
code files may be entirely lower case and will 
still be understood by ASMB. However , even though 
internally ASMB treats them the same, when listing 
out the opcode and cross reference tables, because 
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of the sort routine used, there will be as many 
different entries as there are variations in the 
label or opcode used. For example, the label BEGIN 
will be a separate entry from the label Begin. 
This is actually a useful feature; it is possible 
to have sections of code which use the same data 
labels, but still have the ENTRIES in the cross 
reference table remain separate. Thus, it is 
easier for the user to keep track of the two 
sections while debugging. Note that the two labels 
are ALWAYS equivalent to the Assembler. 


Names (Labels) 


Names are considered to be the labels of all 
instructions as well as the operands of pseudo-ops 
such as ENTRY, EXT, and NAME, Labels may be as 
long as desired (if all on one line); however, only 
up to the first 6 characters are used by the 
assembler. Thus, the first six characters of a 
label may not be duplicated in another label. The 
first character of a label must be an alphabetic 
character or " or "$"; the remaining characters 
may be " . " , "$", or any alphanumeric (A-Z , a~z, 0- 

9). The delimiter for a label is generally a 
colon-space, colon-tab, or a colon-CR-LF. However, 
the colon may be eliminated IF the label begins in 
column one. Note that this means that opcode 
mnemonics may NOT begin in column one. The operand 
may follow the colon immediately if desired. 

The following labels are illegal because the 
Assembler considers them to be register names: 

ABCDEFHLIR 

AF BC DE HL SP IX IY 

These symbols are also illegal if written in lower- 
case. 
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Opcode Mn emon i cs 


The ASMB Assembler recognizes all standard Z- 
80 mnemonics. For the reader who does not have 
familiarity with these, they are well documented in 
the Z-80 CPU Technical Manual published by both 
Zilog and Mostek. The following mnemonics are 
recognized by ASMB in BOTH the forms shown. ASMB 
recognizes these opcodes in the form published by 
Zilog and Mostek : 

ADC A, s ; ADD A,n; ADD A,r; ADD A, { HL) ; ADD A,(IX+d); 
ADD A , ( I Y+d } ; SBC A,s; IN A,(n); OUT (n),A. 

ASMB also recognizes them in this abbreviated form: 

ADC s; ADD n; ADD r; ADD (HL); ADD (IX+d); ADD (IY+d); 
SBC s; IN A,n; OUT n,A. 

In addition the Assembler will allow either of the 
formats shown for the following four instructions: 


in 

0 

or 

IM 0 

IM 

i 

or 

IM1 

IM 

2 

o r 

IM2 

DJNZ 

nn 

or 

DJNZ ,nn 


Opcodes may beg in on any column of a line 
EXCEPT column one. They may be preceded by a 
label. They must be followed by a space or tab as 
a delimiter between the opcode and the operands, or 
if there are no operands and no remarks, the line 
is terminated by a CR-LF. 

Pseudo-opcodes are a special f o rm recognized 
only by the Assembler and for which no object code 
is generated. The conventions of ASMB for pseudo- 
ops are described in other sections. Some of the 
common ones are ORG , EQU , EXT , ENTRY , DEFB , DEFS , 
DEFM, and END. 

A special type of opcode is the MACRO name; 
when this is listed in a column of source code, 
ASMB will insert the corresponding code of the 
MACRO at assembly time. For more information on 
this see the description of MACROS in Chapter 5. 
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Operands 


Operands may consist of register names, 
constants, label names, or expressions. Register 
names include all standard Z-80 registers. These 
are documented in the Z-80 CPU Technical Manual 
published by Zilog and Mostek for the reader who is 
not familiar with their names or purposes. 
Constants consist of one of the five types outlined 
in the Constants section below. Names may include 
DATA labels, program segment labels, subroutine 
names, COMmon names, EXTernals, ENTRY names, EQUate 
statement labels, or the like; they must be set up 
as described in the Names section above. NOTE that 
names of Macros may not be used as operands; 
instead, they are used as opcodes and the assembler 
will substitute the correct code at assembly time. 
Also note that "operands" for statements such as 
the TITLE and *INCLUDE statements are not operands 
in the sense described here and are subject to 
other restrictions. 


Constants 

ASMB allows binary, octal, hexadecimal, 
decimal, and ASCII constants according to the 
following conventions: 

Binary - Numbers formed from binary digits 
{0,1) and terminated by the character 'B 1 . 

Rang e : 

1 11 11 1 11111111 llB<=n<=l 11111 1 111111111B. 
Example: LD BC , 1 01 01 1 0 11 1 1 01 0B 

Octal - Numbers formed from octal digits (0-7) 
and terminated by the character 1 Q r . 

Range : -1 77777Q<=n<=l 77777Q . 

Example: LD BC,25572Q 

Hex - Numbers formed from hexadecimal digits 
(0-9 and A-F) and terminated by the character 
' H ' . A hex number beg inning with a letter 
MUST be preceded by a '0' to distinguish it 
from a label or register name. 

Range: -0FFFFH <=n<=0FFFFH. 

Example: LD BC,2B7AH 
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Decimal - Numbers formed from decimal digits 
(0-9) and EITHER left unterminated or 
terminated by the character 'D'. 

Range: -65535<=n<=65535. 

Example: LD BC, 11130 

ASCII - Numbers represented by the ASCII 
character(s) itself (themselves) enclosed in 
single quotes. 

Range: * 1 through ' ~ 1 which amounts to 

the values 20H through 7EH, including all 
alphanumerics and punctuation. 

Example: LD BCf'+z' 


Note that each of the previous 
produce the same val ue in the BC 
assembly and execution. 


exampl es wi 11 
register upon 


Current Program Counter - $ 


The "$" character may be used in the operand 
of any opcode allowing expressions as operands. 
The "$" is used to represent the current location 
counter of the Assembler. Note that "$" points to 
the BEGINNING of the instruction which contains it 
and not to the end. An example of the way to use 
it is : 


DATA : DB 

COUNT: EQU 


0,11,3,2,7,24,17 
$ - DATA 


The name COUNT thus has the value of seven, because 
this is the number of entries in DATA (the address 
of DATA subtracted from the current location). Now 
elsewhere in the source program, the name COUNT can 
be used to stand for the number of entries in DATA. 
There is great advantage to this representation; if 
it becomes necessary to change the number of 
entries of DATA and re-assemble, the value of COUNT 
will be changed automatically. Whereas if an 
absolute 7 were used instead of COUNT, every 
occurrence of the 7 in the source program would 
have to be changed. 


The 
actually 
the "$" 
way to 
location 
operand 


"$" is often used in another way which is 
poor programming practice. That is to use 
in a relative jump instruction. The best 
handle relative jumps is to label the 
to be jumped to, and use this label as the 
of the jump instruction. ASMB will then 
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calculate the correct displacement (see also "range 
error" in Chapter 6). Remember that "$" represents 
the location counter at the start of the CURRENT 
instruction. 


Expressions and Operators 

The Assembler allows expressions to be used as 
operands, which it evaluates at assembly time and 
places the calculated values in the object code. 
These expressions may be used in place of either 
ad dress or constant operands, provided they do not 
evaluate to an illegal quantity. The following 
operators may be used to form expressions. 
Ope rators which are symbols (eg, " + " } should NOT be 
separated from their operands by a space. 
Ope rators written as one or more letters MUS T be 
separated from their operands by a space. It is 
sometimes desirable to group operations; however, 
parentheses could cause confusion since they are 
also used for memory references. Therefore, 
brackets ("[" and "]"} are also acceptable to group 
the operands of expressions. Parentheses may be 
used provided they do not begin an expression or 
enclose one. Some examples will illustrate this; 
the following are legal expressions, but they may 
be different from what the programmer wished: 

LD A, (X+Y) /Z 

LD BC, (Q+R-S ) 

In the first example the "/Z" is ignored and the 
expression evaluates to the contents of the address 
X+Y. The expression of the second example means 
the contents of the address given by Q+R-S. These 
examples may be rewritten slightly to chang e their 
mean i ng s : 

LD A, [ X+Y ] /Z 

LD BC, [Q+R-S] 

Now in the first example, the QUANTITY of X added 
to Y and divided by Z is loaded into A, and not the 
CONTENTS of this address. In the second example 
also, the brackets mean QUANTITY, whereas 
parentheses would mean CONTENTS. (Note that 
neither brackets nor parentheses are required in 
this example.) An example in which either 
parentheses or brackets may be used because the 
meaning is not am big uo us is: 
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ADD A,Z/(X+Y) 

The following lists the legal operators for 
expressions along with an explanation of each: 

4 - Addition or Plus - binary or unary 

Subtraction or Negative - binary or unary 

* Multi plication 

/ Division 

MOD Modulus - compute the remainder of a division 

X MOD Y is defined to be X- { Y*INT (X/Y) ) 
if X=2 3 and Y=7 then X MOD Y=2 


> or GT Greater Than - true if the left operand is 
greater than the right operand 

GE Greater Than or Equal - true if the left operand is 

greater than or equal to the right operand 

< or LT Less Than - true if the left operand is 
less than the right operand 

LE Less Than or Equal - true if the left operand is 

less than or equal to the right operand 

- or EQ Equals - true if the left and right 
operands are equal 

NE Not Equal - true if the left and right 

ope rand s are not equal 

SHL n Shift Left Log ical - shift n places 
if X=2 AH then X SHL 1 = 54H 

SHR n Shift RIGHT Logical - shift n places 
if X=2 AH then X SHR 2=0AH 

NOT Logical Not - unary 

AND Logical And 

if X-C0H and Y=4 7H then X AND Y=4 0H 

OR Log ical Or 

if X=C0H and Y=47H then X OR Y=C7H 

XOR Exclusive Or 

if X=C0H and Y=47H then X XOR Y=87H 
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ASMB considers these operators to have a hierarchy 
that determines which take precedence over others* 
The list which follows gives this hierarchy, 
progressing downward from those of highest priority 
to those of lowest priority? all those operations 
on any given line are of equal priority* Thus, 
operators which are on the same line of the 
hierarchy would be evaluated from left to right as 
they occur in an expression* However, operators or 
parts of expressions enclosed in parentheses or 
brackets are evaluated first, beginning with the 
innermost set. The hierarchy is; 


*, /, MOD r 

SHL, SHR 

+ > ~ 

( una r y) 

+ 1 ~ 

(binary) 

NOT 

( una r y) 

AND 


OR , XOR 



>, <, =, GT, LT, EQ, NE, LE , GE 

All operations not marked are assumed to be 
binary* If the result of an expression is 0, the 
expression is false; if the result of an expression 
is other than 0 (specif ical ly -1}, the expression 
is true. Also two operands which are equal result 
in a true expression; two that are not equal result 
in a false expression* This information is 
important for determining how to satisfy the IF 
operand* See the chapter on Conditional Assembly 
and Macros for more information on the IF 
statement* Also, see the chapter on Error Messages 
(specifically "Expression Error") for information 
on which of the above operators may be used with 
labels belonging to relative (REL) program 
segments . 


Remarks 


The remarks field is free-fo mat including any 
printable ASCII characters as long as the comment 
is preceded by a ’ ? f * The remark may follow an 
opcode, operand, or label or may exist on a line by 
itself. The 1 ; 1 may be in column one if it is 
desired to have the remark on a line by itself. 
Multiple blanks or tabs may be used before or 
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within the remark to improve readability. A CR-LF 
terminates the remark. Remarks may appear on any 
line, i.e., following any of the legal opcodes or 
pseudo-ops except TITLE and FORM. 
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CHAPTER 4: 

PSEUDO-OPCODES RECOGNIZED BY THE ASSEMBLER 


The following section contains an alphabetical 
list of the pseudo-ops recognized by ASMB. They 
are all listed here for convenient reference; 
however, several of the pseudo-ops are described in 
other sections. Certain of the pseudo-ops require 
labels? others require no label. More information 
on this may be found under "missing label" and 
"label not allowed" in the chapter on error 
messages. Macros and Conditional Assembly are 
explained in detail in a separate chapter. 


A1 phabe t ical List of Pse ud o-ops 


ABS (Absolute code segment) 

The ABS pseudo-op is described in the Source 
Code Segments section at the end of this chapter. 


COM (COMmon code segment) 

The COM pseudo-op is described in the Source 
Code Segments section at the end of this chapter. 


DATA (Data code segment) 

The DATA pseudo-op is described in the Source 
Code Segments section at the end of this chapter. 


DB or DEFB (Define Byte) 

The DB pseudo-op is used to tell the Assembler 
to reserve a byte or string of bytes as data in the 
object code. The bytes may be specified using any 
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of the forms of constants described in the 
Constants section of Chapter 3, or as a series of 
labels which have been previously defined or 
EQUated to a value. NOTE that if the value of the 
label or constant exceeds the range 0 to FFH (or 
its equivalent representation in decimal, octal, or 
binary), the DR will generate an expression error 
and insert a null* Also note that either of the 
terms DB or DEFB may be used. The format of the DB 
pseudo-op i s : 

<Labei:> DB <Item or List of Items> 

where the label is optional and the item or list is 
any of: a byte, a string of bytes separated by 
commas, a string of ASCII characters, or an 

expression or string of expressions following the 
rules for expressions outlined in Chapter 3 (note 
that the expression must be equivalent to an 

absolute byte). The length of the string of bytes 
is limited by the length of a line for ASMB (80 
total characters). A string of ASCII characters 
must be enclosed in single quotes. If it is 

desired to represent the single quote itself in a 
string, it must be given as two adjacent single 

quo tes ( 1 1 ) * Some exam pies will illustrate the use 
of DB : 

DB 'how are you?' (the string will be 

converted to ASCII 
bytes and stored in 
consecutive memory 
locations in the object 
code) 

DB -2,-4,-6,10,11,17 (in order the hex bytes 

which will be stored 
ar e : FE, FC, FA, 0A, 

0B , 11) 


DL or DEFL (Define Label) 

The DL pseud o-op is similar to the BQUate 
statement and is used to define the value of a 
label. The major difference between DL and EQU is 
that DL can be used to set a label to different 
values at different times in the assembly of a 
particular program. The format of DL is: 

<Label:> DL <Expression> 
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where both the label and the expression are 
required. The expression may be in the form of 
another label or an arithmetic expression which is 
a combination of names or constants and which 
follows the conventions for expressions outlined in 
Chapter 3. However, note that the expression can 
NOT be a string of bytes, nor can the expression 
use any EXTernal names. The DL command is exactly 
like the SET pseudo-op of some other assemblers. 
An example of its use follows: 

S P , • . . 


4 

A, COUNT 


COUNT 

DL 

COUNT-1 


LD 

B, COUNT 


END 

START 


In this example COUNT is redefined later in the 
source program from its original value. Note that 
only the original definition of COUNT need be 
changed for both of them to be changed upon re- 
assembly. 

It's important to note here that the DL 
command is quite unlike the DB , DM, DS, and DW 
commands although their formats are all similar. 
These other commands all cause the Assembler to 
reserve a specified number of bytes in the object 
code, whereas DL is an Assembler DIRECTIVE, but 
does NOT reserve any bytes . The DL statement i s 
used to define a value or values internally to 
ASMB. 


DM or DEEM (Define Message) 

The DM pseudo-op is similar to the DB pse udo- 
op except that the DM command sets the high bit 
(Bit 7) of the last byte in the string of bytes 
following the command, when this string is 
converted to object code. This is a very 
convenient feature for defining ASCII strings (in 
which Bit 7 is not used), provided the user-program 


START: LD 

COUNT DL 
LD 
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tests this bit to determine the end of a string. 
Note that the DB command leaves the high bit of the 
last byte unchanged. The format of DM is: 

<Label:> DM <Item or List of Items> 

where the label is optional and the item or list is 
any of: a byte, a string of bytes, a string of 

ASCII characters, or any expression or string of 
expressions following the rules for expressions 

outlined in Chapter 3 {expression must evaluate to 
be 8-bit absolute, however). As was the case for 
DB , a string of ASCII characters must be enclosed 
in single quotes ('), If it is desired to 
represent the single quote itself in a string, it 
must be given as two adjacent single quotes. An 
example of the use of DM is: 

CR: EQU 0DH 

LF: EQU 0AH 

STRING: DM 'this is a string ' ,CR, LF 


In this example the last byte of the string {LF or 
0AH) would be placed in the object code as 8AH with 

the high bit set. Note that the 1 eng th of a DM 

command is limited to the 80-character total line 
length of ASMB. Allowing for a space in column 1, 
the characters "DM", a space, the opening " ' " , and 

the CR at the end of the line; this means that the 

maximum length of a single string using the DM 
command is 74 characters. However, preceding DB 
statements may be used to accommodate longer 
str ing s . 


DS or DEFS (Define Storage) 

The DS pseudo-op is used to tell the Assembler 
to reserve a specified number of bytes in the 
object code for storage. Note that ASMB will not 
insert any particular values in these reserved 
bytes. The format of the DS command is: 

<Label:> DS <Expression> 

where the label is optional and the expression is 
either a constant or an expression which evaluates 
to an absolute and which follows the rules for 
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expressions outlined in Chapter 3. Please note 
that all the terms of the expression used MUST have 
been previously defined in the source code or an 
error will result. A constant value of 1 causes 
ASMB to reserve one byte. An example of DS is: 

ADDRSTABL: DS 20 

in which 20 bytes are reserved by a program to be 
used as an Address Table of 10 entries (two bytes 
per entry). Note that either of the terms DS or 
DEFS is allowed by the Assembler. 


DW or DEFW (Define Word) 

The DW pseudo-op is used to tell the Assembler to 
reserve a word or string of words in the object 
code. A word is defined to be 2 bytes. Thus, the 
DW pseudo-op might be used to specify a look-up 
table of absolute addresses. The words may be 
specified using any of the forms of constants 
described in the Constants section above, or a 
label which has been previously defined or EQUated 
to a word. Note that either of the terms DW or 
DEFW is recognized by ASMB. Also note that the 
Assembler places the low byte FIRST, treating every 
word of two bytes as though it were an address. 
For example, the word "0C923H" would appear in the 
object file as the two bytes, "23H" followed by 
"C9H". Likewise, if LABEL1 had been previously 
defined as "0C923H’', a "DW LABEL1" would generate 
the same two bytes, "23H" followed by "C9H" . This 
follows the conventions described elsewhere for 
expressions or labels used as operands anywhere in 
the source code. In general the DW pseudo-op is 
associated with addresses and the DB statement with 


data ; 

however 

, this is by 

no 

means an absolu 

te * 

The 

DW pseuc 

to-op is a very 

convenient way 

fo r 

enter 

ing addresses because 

the 

user does not n 

eed 

to ke 

^ep track 

of placing 1 

the 1 

ow byte before 

the 

high 

byte; 

s impl y enter 

an 

add r ess as 

i t 

i s 

written. The 

format of DW 

i s : 





< Label : 

> DW < Item or 

List 

of Items> 



where 

the labe 

>1 is optional 

and 

the item or 

list 

i s 

any 

of: a 

word, a s t 

ring 

of words. 

or 

an 

expression or 

string of ex 

:pr ess ions fo 1 lowi ng 

the 

rules 

for expressions outlined 

in Chapter 

3 

and 

evaluating to 

an absolute word 

or string of 

wo rd s . 
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The length of the string of words is limited to the 
80-character total line length expected by ASMS. 
However, successive DW commands may be given to 
accommodate longer tables of words - 

Unlike the DB statement, an expression which 
exceeds the legal range for a DW will not cause an 
"expression error" . Instead , the expression will 
be evaluated modulus 65,536- See "value error" in 
the chapter on error messages for a further 
explanation of this- Note, however, that with the 
DW statement ASCII character strings longer than 
two bytes are not allowed. Some examples will 
illustrate these ideas: 


DW 

'AA' 

( evaiua tes 

to 4 1 4 1 H ) 

DW 

'A' 

( eva 1 ua tes 

to 004 iH} 

DW 

’ ABC’ 

{illegal 
longer than 

, expression 
one word) 

DW 

1 0 0 H , 1 AC H , - 8 1 4 

(multiple 

expressions, 


evaluates to the hex 
bytes f in order: 00, 01, 

AC, 01, D2, FC) 


END ( End of assembly) 

The END pseudo-op is used to terminate 
assembly of a block of source code- The format of 
END i s : 


<Label:> END <Expression> 

where the label is optional and the expression is 
subject to these rules: ONLY the main module of a 
program should have an expression or name 
following, and this module MUST have this 
expression* The expression should be equivalent to 
the entry point of the module at which execution 
will begin* All other modules are then terminated 
with the END statement alone and are thus 
considered by ASMB to be sub-modules. The reason 
for this convention is that the Linker/Loader must 
know in which of the modules and at what address to 
begin execution* The quantity in the Expression 
may contain any legal operators (see section on 
Expressions in Chapter 3)* Following is a sample 


44 



CROMEMCO MACRO ASSEMBLER 


use of the END statement to terminate assembly of a 
main module: 




ENTRY 

MAIN 


MAIN: 

LD 

SP, 1800H 



END 

MAIN 

whereas 

this 

example 

shows termination of a sub' 

mod ul e 

to be 

linked to 

the main module: 



EXT 

MAIN 


BEGIN 

: LD 

A, 10 


END 

The END command is a signal to the Assembler 
that a logical body of code is complete. 
Therefore, only one END statement should appear in 
a module. Should the END appear in the middle of a 
block of code, everything following the statement 
will be ignored by ASMB. 


ENDIF {END of IF definition) 

The ENDIF pseudo-op is used to terminate 
Conditional Assembly of a block of code which 
follows an IF statement. The formats of IF and 
ENDIF are described in detail in the following 
chapter on Macro and Conditional Assembly. 


ENTRY (Entry point for these mod ule s ) 

A program module may be assembled with 
unresolved addresses providing they are declared 
EXTernal in that module. Any address declared 
EXTernal to one module must be declared an ENTRY in 
another module. These two modules are eventually 
linked. Since these addresses are unresolved, they 
are represented in the EXT and ENTRY statements as 
label names. The names then become a part of the 
.REL file. The Linker/Loader reads the .REL files 
at run time, determines the unresolved addresses, 
and places their correct values in those bytes 
which expect the addresses. If the Linker is 
unable to resolve an ad dress, it prints the 
undefined label name on the console followed by an 
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asterisk (see Part II for more information on 
LINK ) . 

The ENTRY pseudo-op is used to declare in a 
source-file that that file contains the entry 
point(s) of the listed names. These names may be 
label names of subroutines, or program or data 
blocks. The format of the ENTRY command is: 

(no label) ENTRY <Name 1 , Name2 , . . . > 

The number of names used as operands of the 
ENTRY pseudo-op is limited only by the total line 
length (80 characters). Extra names in ENTRY not 
actually defined in the source-file will produce 
the error message "undefined symbol". ENTRYs may 
appear anywhere within a program module, but are 
typically written at the top of a file to be easily 
seen in the print-listing. ENTRY labels (standing 
for corresponding addresses) can be referenced by 
any other module which declares those names to be 
EXTernal (see EXT section). Refer to Part II on 
the Linker for information on linking these modules 
at run time. 

Below is an example of a module which uses an 
ENTRY statement to demark two subroutines and a 
table of data: 



ENTRY 

METRIC, ENGLIS, 

CONTBL 

METRIC : 

* • 9 

m 

RET 

;metric-to-English 

conversions 

ENGLIS : 

RET 

; Eng 1 i sh- to -me tr ic 

conversions 

CONTBL: 

• * • 

END 

; conversions table 



The corresponding example of a program module 
which calls these sub routines is given with the 
description of EXTernals. 


EQU (Equate) 

The EQU pseudo-op is used to inform the 
Assembler that two named quantities are equivalent. 
The fo rma t of EQU i s : 

<Label:> EQU <Item> 


46 



CROMEMCO MACRO ASSEMBLER 


where the label is required and the item is any of: 
a constant, an address, a label, or an expression 
following the rules given in Chapter 3. Note that 
all the terms of the expression MUST have been 
previously defined. Also, the expression may NOT 
involve the names of any EXTernals. 

The EQU statement is used to equate a label to 
a particular value. Once this label is defined, it 
is defined for the entire source program. The DEFL 
command should be used for labels which are to 
change within a module. EQU is a useful statement 
for simplifying or clarifying source code. For 
example suppose the ASCII characters for carriage 
return (CR) and line feed (LF) were to be used 
throughout a source program. Instead of using 

their values, a clearer procedure would be to enter 
the lines: 

CR: EQU 0DH 

LF: EQU 0AH 

somewhere in the source program and then use the 
names " CR" and " LF" to stand for the values as in: 

STRING: DB 'end of text',CR,LF 

The EQU statement is also very valuable for 
changing a quantity quickly and in all places. 
Suppose that it is desired to test a program with 
different values for a timer. Suppose further that 
this value is used 10 times throughout the source 
code. If the original value is used in each of 
those 10 places, then all 10 will have to be 
changed to change the timer. However, if each of 
the 10 places uses the label "TIMER" and the 
following statement appears somewhere in the 
module : 

TIMER: EQU <value> 

then this statement can very easily be changed by 
ed i ti ng . This assures upon r e-a ssembly that all 
the places TIMER occurs will be changed. 


EXT or EXTRN (these modules External) 

Using ASMS, program modules may be assembled 
with unresolved addresses. The EXT pseudo-op is 
used to declare in a source-file that that file 
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must depend on some other module(s) to satisfy 
certain EXTernal names. The EXT and corresponding 
ENTRY names become parts of the two .REL files; the 
addresses are then resolved at run time. Further 
information about this is described in the first 
paragraph under the ENTRY pseudo-op; information 
about linking and running files is given in Part II 
on the Linker. The format of the EXT command is: 

(no label) EXT <Namel , Name2 , . . . > 

where the names may be label names of subroutines, 
or program or data blocks. Note that Module Names 
under the NAME pseudo-op may NOT be used in the EXT 
fields of other modules. The number of names used 
as operands in an EXT pseudo-op is limited only by 
the total line length of ASMB (80 characters). 
Either of the forms EXT or EXTRN is accepted by the 
Assembler. EXTs may appear anywhere within a 
program module, but are typically written at the 
top of a file to be easily seen in the print- 
listing. When the assembled modules are linked and 
run, all EXTs must be satisfied by corresponding 
ENTRYs in other modules or the Linker will return 
an error message. 

It is important to note that label names 
declared EXTernal to a module may be used as 
operands within the module, but may NOT be used in 
expressions. For example the following lines would 
be legal : 


EXT 

COUNT 

LD 

A, COUNT 


whereas the following would be illegal and generate 
an error: 

EXT COUNT 


LD A , COUNT+3 


Also note that a label name declared as an EXTernal 
to a module may NOT be redefined (i.e., used in the 
label field) within that module. 
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Below is an ex am pi e of a module which uses an 
EXTernal statement to declare the names of two 
outside subroutines and a table of data: 


START: 


EXT 

METRIC, ENGL I S,CONTBL 

* «- ■ 

LD 

HL, CONTBL 

LD 

A, (HL) 

CALL 

METRIC 

INC 

HL 

LD 

A, (HL) 

CALL 

ENGLIS 

END 

START 


The corresponding example of the module which 
contains these subroutines is given with the 
description of ENTRY pseudo-ops. 


FORM (paper Formfeed) 

The FORM command is used to advance the paper 
in a print listing to the top of the next page. 

The format of FORM is: 

(no label) FORM (no operands) 

FORM is used for clarity in a print-listing, 
as the beginning of a routine can be more clearly 
identified if it starts at the top of a page. The 
FORM command in the source code will not be printed 
on the listing. Multi pi e FORM commands may also be 
used; however, each page will be numbered and 
titled by ASMB. The command "EJECT" may be used in 
exactly the same way as FORM to force a pa pe r-f eed 
to the top of the next page. 

The Assembler implements FORM by issuing a 

series of linefeeds to the printer; the number of 

linefeeds needed to reach the next page is 

determined by ASMB from the TOP= and PAGE= options. 
The only exception to this is that when TOP=0 has 
been selected, an actual formfeed character is 
issued to the printer. In this case the printer 
will advance according to the paper size for which 
it is designed. 
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IF (begin Conditional Assembly) 

The IF pseudo-op is described in the following 
chapter on Mac ro and Conditional Assembly . 

* INCLUDE {Include the given disk file) 

The * I NC LUDE pseudo-op is used to specify a 
source- file on disk which is to be included in the 
assembly of the present source. The fo rrna t of the 

* INCLUDE command is: 

* INC LUDE <d : f i 1 enarne . ex t> 

where d stands for the disk drive letter (A-D) , and 
filename is the user's disk filename, which may or 
ay not include a 3-letter extension. If the disk 
rive letter is omitted, ASMB assumes the file is 
on the current drive. It is IMPORTANT to note that 
the *INCLUDE statement MUST begin with the asterisk 
in column one. Hence, NO label field is permitted 
with this opcode. The filename may follow the 

* INCLUDE after at least one delimiter (space or 
tab). Another important point to notice about the 

* INCLUDE is that all of the given file is Included 
in the present file. Hence, if the included file 
has an END statement, this END statement will 
terminate assembly of the present source when it is 
encountered. An ex am pie will illustrate this; 
suppose this is the source-file to be assembled: 

BEGIN: LD SP, . . . 

* INCLUDE A : US ERF I LE . Z80 

LD HL, 

LDIR 

END 

and suppose the following is US ERFI LE . Z80 : 

START: LD BC, 

LD DE , . . . 

END 

Because the USERFILE contains an END 
statement , the Assembler will never see the LD and 
LDIR instructions of the source- file. Assembly 


50 



CROMEMCO MACRO ASSEMBLER 


will be terminated following the inclusion of 
USERFILE. To avoid this problem simply leave off 
the END statements of files which are to be 
INCLUDEd in the assembly of other files, or put the 
*INCLUDE statement as the last one in a source 
program and leave off that source's END statement. 

The *INC LUDE statement is particularly useful 
in conjunction with Conditional Assembly blocks of 
code (see the discussion of the IF statement in the 
next chapter). For example a file may be INCLUDEd 
depending on whether or not an IF statement is 
satisfied. Also, the IF statement can be used to 
determine which of several files will be INCLUDEd. 
An example of this use of *INCLUDE follows; one of 
three different files will be included and the 
others ignored dependent on the value of the label 
DECIDE (defined earlier in the source): 


IF DECIDE EQ 0 

* INCLUDE A : MOVROUTN . Z80 

ENDIF 

IF DECIDE EQ 1 

* INCLUDE B: SAVROUTN. Z80 

ENDIF 

IF DECIDE EQ 2 

* INCLUDE LOADROUT. Z80 

ENDIF 


where the first file would be found on drive A, the 
second on drive B, and the third on the current 
drive. The entire block of code above could be put 
in a file of its own called DECIDFIL. The user 
source file would initialize the variable DECIDE 
using an EQU or DL statement and give the command 
" * INCLUDE DECIDFIL". Then, based on the value of 
DECIDE, the routine which would be included would 
be either the move, save, or load routine above. 

*INCLUDEs may be nested up to four levels; 
more than this will generate a nesting error. The 
example above illustrates two levels of nesting: 
the user file INCLUDES the file DECIDFIL, which in 
turn INCLUDES one of the files MOVROUTN, SAVROUTN, 
or LOADROUT. It is possible to write a source 
program which consists of *INCLUDEs only. 


51 



CROMEMCO MACRO ASSEMBLER 


LIST (use following commands to generate Listings) 

The LIST pseudo-op is used to set the 
Assembler print-listing options. This at NO TIME 
affects the actual object code put out by ASMB. It 
Is simply used to suppress undesired or repetitive 
sections of the listing file. The format of the 
LIST statement i s : 

(no label) LIST <Opt ionl , Opt i on2 , . . . > 

where the options are taken from the list of six 

legal operands which follows this paragraph. The 
number of options which may be placed on a line is 

limited only by the line length. However/ 3 

options is the practical limit because more than 
this will result in duplicate or conflicting 
options. Options may be g iven in any order. If 

conflicting options are given (conflicting options 
are the pairs gen-nogen, cond-nocond, on-off), only 
the last one of the pair on the line will be used. 

The LIST command may be used as often as 
desired throughout a sourcecode file. However, 
note that if the List Options of Chapter 2 are 
issued at the time of the CALL of ASMB, these will 
override any corresponding LIST commands given in 
the SOURCE. For example if the List Option "Gen" 
is specified when calling ASMB, all "Nogen" 
operands of LIST in the source would be overridden. 
However, the OTHER operands of LIST in the source 
would still be effective. Following are the six 
allowable operands of the LIST pseudo-op. 
Information on the use of List Options when calling 
ASMB will be found in Chapter 2. 


OFF (turn Off assembly listing) 

Suppress print-listing until end of code or an 
ON option. This option is de-select ed when 
assembly of a program begins (before encountering a 
LIST pseudo-op) . 
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ON (turn On assembly listing) 

List print-listing to disk-file or console 
until end of code or an OFF option. ON is the 
default when assembly of a source file begins. 


COND (begin listing Conditional Assemblies) 

Force the generation and printing of all 
blocks of code which are parts of IF definitions, 
until end of code or a NOCOND option. COND is the 
default when assembly of a source file begins; 
therefore, it would generally be expressed only to 
override a previous NOCOND option. Note that COND 
forces the printing of IF statements but NOT the 
assembly of them; that is determined by whether the 
IF statement is true or false. 


GEN (begin listing Generated Macros) 

Force the printing of the Macro expansion 
following every Macro call, until end of code or a 
NOGFN option. GEN is the default when assembly of 
a source file begins; therefore, it would generally 
be selected only to override a previous NOGEN 
option. 


NOCOND (do Not print Conditional Assemblies) 

Force no printing of IF or ENDIF statements 
and no printing of IF definitions (the code 
following the IF) if the IF statement is false. 

In other words an IF definition which is not 
assembled due to its being false will not be listed 
in the pr i n t- 1 i s t i ng either. This option will 
remain selected until the end of code or a COND 
option. The option is de- selected when assembly of 
a program begins and thus must be first selected 
using the LIST pseudo-op. Selection of NOCOND in 
NO WAY affects the object code of an assembled 
file. 
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NOGEN (do Not print Generated Macros) 

Force no printing of Macro expansions. 
However, note that Macro definitions are always 
printed as are the Macro calls themselves; it is 
only the code which the Macro generates which is 
not printed. This option will remain selected 
until the end of code or a GEN option. The option 
is de- selected when assembly of a program begins 
and thus must be first selected using the LIST 
pseudo-op. Selection of NOGEN in NO WAY affects 
the object code of generated macros of an assembled 
source file. 


MACRO (begin Macro definition) 

The MACRO pseudo-op is described in the 
following chapter on Macro and Conditional 
Assembly. 


MEND (Macro definition End) 

The MEND pseudo- op is used to terminate the 
block of code which forms a Macro Definition. The 
formats of MACRO Definitions and Calls, and the 
MEND statement are described in detail in the 
following chapter. 


NAME (module Name) 

The NAME pseudo- op is used to assign a name to 
a particular module for use by the Linker. This 
name is, however, written in al phanumer ics so it is 
also useful to the programmer for remembering the 

purpose of the module. The format of NAME is: 

(no label) NAME <Module Name) (1-6 characters) 

where the module name should follow the same syntax 
rules as for labels. The NAME statement is 

optional; it is not required for linking of 
modules. However, if the NAME statement is 

omitted, the Assembler automatically assigns the 
first six characters of the filename to be the 

module name. Note that NAME is different from 
TITLE. The TITLE statement merely tells A SMB to 
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print a heading at the top of each page of the 
listing but has no effect on the object code; NAME 
forces the name of the module to be saved as part 
of the .REL file. Thus, a library manager program 
is able to locate .REL files by name. 


ORG (Origin) 

The ORG pseudo-op sets the Assembler location 
counter and is used when it is desired to start 
assembly of a block of code at a particular 
address. This location may be set by the user to 
be absolute, or it may be left up to the Assembler 
to determine the value of the ORG. The location 
counter may be set to a value as often as desired 
in a source program; that is, multiple ORG 
statements may be used. The format of the ORG is; 

<Label:> ORG <ABS Address, Label Name, or Expression> 

where the label is optional but the expression or 
address is required. The VALUE of the ORG (i.e., 
the address of the first statement following the 
ORG) is determined by the value of the label or 
expression. Note that all the terms used in the 
expression MUST have been previously defined. The 
TYPE of code segment which will follow the ORG is 
determined by the type of code segment to which the 
label or expression belongs. For example, the 
statement "ORG LEFT OFF" would continue a COMmon 
area if LEFTOFF belonged to a COMmon area, and 
would continue a RELocatable area if LEFTOFF 
belonged to a RELocatable program area. In either 
case, however, the value of the ORG would be 
determined by the value of LEFTOFF. The statement 
"ORG 100H" would begin an ABSolute program area 
since the address is absolute. Note that the ORG 
pseudo- op does not reserve any byte s , but merely 
specifies an address at which those bytes are to 
begin. 


REL (Relocatable code segment) 

The REL pseudo-op is described in the Source 
Code Segments section at the end of this chapter. 


55 



CROMEMCO MACRO ASSEMBLER 


REM (Remark beg inning in column one) 

The REM statement is another method of 
designating a remark; however, REM assures that the 
remark is always printed begining in column 1 of a 
print-listing without any characters preceding (as 
with the The REM pseudo-op itself is never 

printed as is also the case with the FORM and TITLE 
printer-controls. The format of REM is: 

(no label) REM <Remark Phrase> (as many char, as will fit) 

The Cromemco 3703 Printer will expand a line 
if the line contains the Control-N (0EH) character. 

This is the reason for the REM statement, to be 
able to give this character at the beginning of a 
remark and have the printer expand the line to make 
it more noticeable. However, when using the 
feature, the user must take care that the remark to 
be printed does not exceed HALF the width 
specification of the Widths option. For example 
most listings use the default value of Width=79; 
thus, the number of characters in the REM statement 
which uses the ~N should not exceed 39. This is to 
prevent the printer from pr int i ng off the side of 
the paper. Also note that the maximum length of a 
REMark is 74 characters. 


TITLE (Ti tl e to be pr in ted at top of each page) 

The TITLE pseudo-op is used to print a title 
at the top of each page of a pr in t- 1 i st i ng 
beg inn i ng in column 1 . The fo rma t is: 

(no label) TITLE CTitle Phrase> (as many char, as fit) 

As with the REM statement, the Title Phrase 
may contain the character Control-N (0EH). On the 
Cromemco 3703 Printer this character will expand 
the line to twice its normal width. For this 
reason when using the in a TITLE statement, the 
number of characters in the Title Phrase should not 
exceed half the number of characters which will be 
specified in the Width= option. The TITLE command 
should be the first line of a program in order to 
be pr in ted on Pag e 1 as well as the other pages. 
Note that titles may be changed in the middle of a 
source program simply by giving a new TITLE 
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command. Also note that in such a case TITLE 
causes an automatic FORM feed. The maximum length 
of a Title Phrase is 72 characters; strings longer 
than 72 are truncated. The Assembler inserts a 
blank line where the Title Phrase would be if TITLE 
is not specified. 


Source Code Segments 


Perhaps the single most important feature of 
the CROMEMCO Assembler is its ability to generate 
relocatable code. This feature allows a user to 
assemble a number of modules of source code 
separately, and link them together in any order at 
run time. It also means that the object code can 
be executed at nearly any address in memory {it is 
generally not advised to assemble and run programs 
over portions of CDOS) . The Assembler can assemble 
all data in locations separate from the program 
area so that either area may be programmed into 
ROM. 


There are four special pseudo-ops which inform 
the Assembler what type of object code to generate. 
This section describes these four Source Code 
Segment pseudo-ops and the ways they are used. 
Explanations of the way relocatabil i ty works are 
given in the following, and information on the 
CROMEMCO Linker/Loader may be found in Part II. 


ABSol ute 

The ABS pseudo-op precedes a code segment 
which is to be assembled in absolute code (absolute 
addresses). The Linker will consider this code to 
be non-r el oca table . The format of ABS is: 

(no label) ABS (no operand) 

All the code following the ABS will be 
considered to be absolute until another Code 
Segment pseudo-op is given. The Assembler defaults 
to REL upon start of assembly of a program; thus, 
if no pseudo-op is given, the object code will be 
relocatable. ABS areas are addressed contiguously 
throughout a source program unless ASMB is told 
otherwise by the use of ORG statements. At the 
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beginning of a program the program counter for ABS 
is set to 0 (however, unless ABS is specified, ASMB 
assumes the REL pseudo-op) unless the user 
overrides it with an ORG. For subsequent ABS areas 
the current contents of the program counter (which 
is the address at which the last ABS left off) will 
specify the loading address. Some examples will 
help illustrate these ideas. Consider the 
following : 

ABS 

START: LD SP , . . . 

END 


In this example the entire source program is to be 
cons id e red absolute and the addresses are to begin 
at 0. If the same example were written: 

ORG 100 0H 

START: LD SP, . . . 

END 


the entire source program is again to be considered 
absolute with the addresses beginning at 1000H. 
Now consider two ABS areas and a DATA scratch-pad 
area between them: 


START: 

ABS 

LD 

SP , * m m 

STOP: 

LD 

HL, - - * 

AD DR 1 : 

DATA 

DS 

2 

ADDR2 : 

DS 

2 

NEXT: 

ABS 

LD 

BC f • • • 


END 



In this example assembly will begin at absolute 
location 0 because no ORG statement is specified. 
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Assembly of the second ABS area will begin with the 
next address following the LB instruction at STOP. 
Note that an ORG statement could have replaced 
either ABS statement to cause the code segment 
following to assemble elsewhere. The DATA area 
will be assembled relocatable. 


COMmon 

The COM pseudo-op precedes a data segment 
which is to be assembled common to more than one 
module. The name and size of the COMmon(s) are 
then saved in the .REL file; this enables the 
Linker to load the addresses correctly at run time 
such that the given area is common to several 
program modules. The CROMEMCO Linker/ Loader is the 
same one used to link .REL files produced by the 
CROMEMCO FORTRAN IV Compiler. Hence, COMmons are a 
very convenient way of enabling a machine language 
subroutine to use a FORTRAN data area, or as a fast 
way to pass arguments between FORTRAN and machine 
language programs. COMmons may be used in this way 
for assembly language programs as well; two or more 
program modules may use the same data scratch-pad 
area for passing arguments. EXT and ENTRY 
statements which apply to data areas may be 
replaced by COMmons. (When interfacing FORTRAN to 
machine language routines, allow four bytes for 
Real, two bytes for Integer, and one byte for 
Logical variables.) The format of COM is: 

(no label) COM <Common Name) (1-6 characters) 

Note that the full word COMMON is NOT allowed 
by ASMS . The Common Name may be omitted in the 
above, and this is considered the blank common. If 
the name is used, it should follow the rules for 
labels given in Chapter 3. Following the COM 
command are the labels and pseudo-ops allocating 
storage. Note that when COMmons are used by more 
than one program module, they must either be the 
same length in every module, or the module which is 
linked first must contain the longest COMmon 
specification so that LINK allocates at least that 
number of bytes . 

Also, note that the COMmons of different 
modules DO NOT have to have the same labels on the 
data. Thus, this COMmon in one module: 
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COM DATA 

ADDRTB : DS 2 0 

COMMTB : DS 10 

and the following COMmon in another module: 

COM DATA 

COUNT: DS 4 

LOOKUP: DS 26 

would assemble and link correctly; they are the 
same 1 eng th and the data labels are transparent to 
the Linker. 

There are 15 different COMmons of equal level 
(i.e., there is no hierarchy) allowed by the 
Assembler in any one program; exceeding this number 
will generate an error. All the code following the 
COM will be considered to be a common until- another 
Program Segment pseudo-op is given. A common may 
also be continued later in the same prog ram segment 
by giving the COM command with the same name as 
before. Using a different name will cause the COM 
location counter for THAT common to start over at 
zero. Remember that COMmons of the same name need 
not be the same length in every module as long as 
the module containing the longest COMmon 
specification is linked first. An example will 
illustrate some of the features of COM: 


BEGIN: 

LD 

SP, . . . 


COM 

INSTRC 

TABLE 1 : 

DS 

REL 

50 


LD 

HL, . . . 


COM 

ADDRES 

LOCATE: 

DS 

20 


COM 

INSTRC 

TABLE2 : 

DS 

50 


END 


Both TABLE 1 and LOCATE in the above will beg in at 
COM location counter zero; however, note that they 
are different commons. TABLE2 will begin at 
location counter 50 for COM INSTRC (thus COM INSTRC 
reserves 100 total bytes as storage). Also note 
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the use of the REL statement to return to 
RELocatable code following the end of the first 
part of COM INSTRC . Generally the DS pseudo- op is 
used to allocate storage area for a COMmon; if the 
DB, DM, or DW statements are used, bear in mind 
that the loaded bytes of the first COMmon may be 
over-written by the second loaded COMmon when they 
are linked. 


DATA 


The DATA pseudo-op precedes a program segment 
which is to be assembled as a block of data. LINK 
will consider this code to be relocatable. The 
format of DATA is simply: 

(no label) DATA (no operand) 

All the code following the DATA will be 
considered to be part of the data block until 
another Code Segment pseudo-op is given. The DATA 

pseudo-op is very similar to REL; DATA is provided 

so that the user may maintain separate data and 
program code segments in a source file. Thus, the 
program segments may be programmed into ROM 
following their being linked and loaded, and the 
data segments may remain in RAM, for example. All 
DATA segments of a program are based upon the DATA 
location counter, which is set to zero upon the 
start of assembly. As is the case with ABS and 
REL, all DATA segments in a program will be 
add r essed con tig uousl y if ORG statements are not 
used to change the addressing. Also, remember that 
an ORG will cause assembly to continue with the 

type of Code Segment to which the expression of the 

ORG statement belongs. For example the following 
section of a source code program: 


LABE LI: 

DATA 

DS 

10H 


REL 

LD 

A, .. 

LABEL2 : 

DATA 

DS 

1 0 H 


END 



would be assembled in exactly the same way as this 
section : 
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DATA 

LABE LI : DS 10H 

REL 

LO A, . . . 


ORG LABEL1+1 6 

LABEL2: DS 10H 

END 

where the ORG statement has replaced the second 

DATA statement. Since LABE LI belongs to a DATA 
area, the ORG statement tells ASMB to return to 

assembling in the DATA code segment without the 
need for the second DATA pseudo-op. For more 

information on the ORG see the list of pseudo-ops 

above . 


RELoca table 

The REL pseudo-op precedes a code segment 
which is to be assembled in RELocatable form. The 
Linker will recognize this code at run time, link 
it with any other relocatable mod ule s , and load 
them into the desired address in memory. 
Relocatability works in this way: following 

assembly, the .REL file contains the locations of 
all bytes wh ich contain unresolved addresses. At 
run time the Linker then determines the pi ace at 
which the program is to be run and correctly fills 
in the unresolved addresses. As the modules are 
linked, LINK also prints the names of any still 
undefined labels (those declared in EXT 
statements) . 

The Assembler defaults to the REL code segment 
upon start of assembly of a program and the REL 
location counter is set to zero. However, other 
code segment pseudo-ops may be specified throughout 
the source, and REL issued to return to relocatable 
code at the end of these segments. The format of 
REL is: 

(no label) REL (no operand) 

The code following the REL will be considered 
to be relocatable program area until another Code 
Segment pseudo-op is given. REL areas are 
addressed contiguously throughout a source program 
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unless ASMB is told otherwi se by the use of ORG 
statements. Note, however, that the ORG will cause 
assembly to continue with the type of Code Segment 
to which the expression of the ORG statement 
belongs (see the example of this in the section 
above on the DATA pseudo-op) . The REL statement is 
generally needed only to return to relocatable 
program code following the use of another Code 
Segment opcode. Note also that data may be 
included in the REL area. The DATA and REL pseudo- 
ops treat relocatable code in an identical manner; 
therefore, unless there is a specific reason for 
keeping the data and program areas separate, the 
DATA statement(s) could be eliminated. 
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| CHAPTER 5: MACRO AND CONDITIONAL ASSEMBLY 


! 

r 


Two of the most powerful features of the 
CROMEMCO Relocatable Assembler are Macro and 
Conditional Assembly. The purpose of this chapter 
is to define and explain these two features and 
illustrate their use with examples. However, the 
user should bear in mind that these examples only 
scratch the surface as illustrations of the uses of 
Macros. It is left up to the readers to adapt 
Macro and Conditional Assembly to their needs. 


Macro Assembly (MACRO definition and calls) 


Macros provide the user with a method of 
producing a block of in-line code in a source file 
without having to generate this block of code each 
time it is required. This block of code is known 
as the Macro body. Macros also allow a great deal 
more flexibility than in-line source code because 
of the ability to accept parameters. This means 
the Macro may be tailored to suit a particular 
purpose. For example suppose a user wishes to use 
a move routine which does a block move of 100 
bytes. Later in the same program, a block move of 
500 bytes is desired. Although these two routines 
could be written separately, it would be much 
easier to write a Macro which accepts the correct 
parameters and generates the correct block move. 
Some other advantages of the use of Macros are: 

-Rewriting repetitive blocks of code is 
not required. The code is written only 
once in the Macro. 

-Macros can be used to improve program 
readability and to create easily-read 
skeleton prog rams. 

-Macros written by a number of 
programmers can be collected in a Macro 
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library which may be used by all. 
Eventually nearly entire programs may be 
written using the Macros in this library. 

-New Z-8 0 instructions may be designed 
using existing instructions in a Macro 
(this is an instruction only to the 
Assembler; it is not possible to add 
instructions to the Z-80 Instruction 
Set) . 


-An error found in a Macro need be 

corrected only once regardless of the 

number of times the Macro is called. 

Some users may wonder how Macros differ from 
subroutines, since subroutines may also be used to 
reduce the coding of frequently executed blocks of 
code. One distinction between the two is that 
subroutines branch to another part of the program 
while Macros generate in-line code. However, a 
Macro does not necessarily generate the same source 
code each time it is called. The source code the 
Macro generates can be changed by changing the 
parameters in the Macro Call. Also, Macro 
parameters can be tested at assembly- t ime by the 
Conditional Assembly (IF) statement. These two 
features enable a general purpose Macro Definition 
to generate customized source code for a particular 
situation. Thus, the biggest difference between 
Macros and subroutines is that Macro expansion and 
customized code result at assembly-time within the 
object code. Subroutines, on the other hand, 
reside in the source program, and require extra 
execution time (especially if the subroutines do 
any conditional operations). There is a trade-off, 
however, between the extra memory required for 
Macros (in-line code) and the longer execution time 
of subroutines. In most cases using a single 
subroutine rather than multiple in-line Macros will 
reduce the overall program size. However, the use 
of Macros may be more efficient in situations 
involving a large number of parameters. Note that 
Macros can call subroutines, and subroutines can 
contain Macro Calls. 

An example of a simple Macro Definition would 
perhaps illustrate some of these points. Suppose 
that there were a number of times in a source 
program that it was des i r ed to exchange the uppe r 
four and the lower four bits of the A register. 
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Although a subroutine could be written to do this, 
the associated CALLS and RETurns would slow down 
execution time. Thus, to save typing when writing 
the source code, a Macro is used: 

ROTATE : MACRO 
RLCA 
RLC A 
RLCA 
RLCA 
MEND 


The general format of a Macro Definition can 
be seen from this example. The word ROTATE becomes 
the Macro name. Thus, to CALL this Macro one would 
simply use the word ROTATE as an opcode in the 
source code, and the Assembler would insert the 
four RLCA opcodes as in-line source code following 
the ROTATE Macro opcode. This is known as the 
Macro EXPANSION. The MEND statement informs the 
Assembler that the Macro Definition is complete. 
Suppose now that rather than be limited to having 
the Macro exchange the high and low bits of the A 
register only, it was desired to have it operate on 
any of the 8-bit registers. The following Macro 
Definition might be used in place of the above: 

ROTATE: MACRO #REGIS 

RLC #REGIS 

RLC #REGIS 

RLC #REG IS 

RLC #R EG IS 

MEND 


This Macro uses the parameter REGIS, the value 
of which it will determine when the ROTATE macro is 
called. The symbol is required to precede the 

parameter(s) everywhere it appears in a Macro 
Definition to distinguish it from other labels; 
however, this symbol is NOT required when 
specifying the parameter in a Macro Call. Since 
ROTATE now expects one parameter, the form of a 
Call would be : 

ROTATE <register> 

where the word "register" would be replaced with 
one of: A, B, C, D, E, H, or L. The Assembler 

would then generate in-line code using the correct 
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register name. For example if the Macro Call 
"ROTATE H" was used, ASMB would generate the in- 
line code: 


RLC H 

RLC H 

RLC H 

RLC H 


Based on the above examples we now give the 
complete format of a Macro Definition and Call. A 
Macro is defined by: 

<Macro Name:) MACRO <# Pa r ameter 1 , #Pa rame ter 2 , . . . > 

<opcodes and 
operands which 
may use the 
parameters of 
the Macro statement 
and which form 
the Macro body> 

(no label) MEND (no operand) 


where the parameters are optional and are 1 im i ted 
in number only by the length of a line for ASMB (80 
characters) . The Macro Name is required and is the 
name used when calling a Macro. The MEND is the 
Macro End statement and is required to inform the 
Assembler that the source code of the Macro is 
complete. The opcodes or pseudo-ops between the 
MACRO and MEND statements comprise the Macro 
Definition, and may be any legal Z-80 instructions, 
calls to other Macros, or ASMB pseudo-ops. 

There are a number of impo rtant po ints to note 
about the above format of Macros. First, note that 
when passing parameters to the Macro the parameter 
name must be preceded by the symbol "#" everywhere 
it appears in the Definition; however, it is NOT 
used to precede parameters in a Macro Call . The 
parameters are actually dummy names; they stand for 
a quantity which will be substituted at assembly 
time. Therefore, the same parameter name may be 
used in several separate Macro Definitions (for 
example #REGIS may be used more than once). The 
parameters MUST follow the syntax rules for 
whatever portion of code they represent. Note that 
the text itself of the actual (not dummy) parameter 
is substituted in the Macro Expansion. Thus, 
register names can be used rather than a val ue 
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which stands for the register as 
assemblers . See the above example wh 
H is used as the parameter. Anothe 


useful is to substitute 
i tsel f : 

for letters 

ROTATE : MACRO 

#DIR, # REG IS 

R#DIRC 

#REGIS 

R#DIRC 

#REG IS 

R#DIRC 

#REG IS 

R#DIRC 

MEND 

# R EG I S 


in some other 
ere the letter 
r way this is 
in the opcode 


In this example either the command RLC or RRC 
could be generated by assigning the letter "R" or 
" L" to the first parameter. However, if the letter 
"Q" was used, this would generate the illegal 
opcode "RQC" , causing an error message when the 
Macro is expanded. A last point to be made about 
parameters in Macros is that parameter names that 
appear early in a list should NOT be subsets of 
parameters that fall later in a list. This is 
because dummy parameter names do not have a 
delimiter (such as a colon) to inform the Assembler 
of their last character; note that parameter names 
do not follow the same syntax rules as label names. 
Dummy parameter names may be as many characters as 
will fit on the line and be composed of any 
printable ASCII characters. An example of an 
i 1 1 eg al use of parameters is: 


LOAD: MACRO #OPER , #OPERND 


where the 
operation 
illegal as 
OPERND. A 


user desired one pa r am e ter 
and the other the operand, 
it stands because OPER is a 
correct example is : 


to be 
This 
subset 


the 
i s 
o f 


LOAD: MACRO #OPERAT, #OPER 


Another important point to be made about the 
format of Macro Definitions concerns the way in 
which labels are defined. Labels appearing in DL 
statements within the Macro Definition are not 
subject to the following restriction because they 
can be multiply defined {see section on Conditional 
Assembly for an example of the use of a DL and an 
IF statement to cause conditional Macro assembly). 
A label appearing on any other statement of a Macro 
Definition will generate a multiple definition 
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error if that Macro is called more than once {the 
second expansion would also reproduce the label). 
To avoid this problem a general label name for 
Macros has been provided, which is used by 
assigning two letters to the label name followed by 
the characters "#SYM" . These four characters are 
replaced by a four-digit number each time a Macro 
is called. The four-digit number starts at 0000 
and is incremented by one each time ANY Macro is 
called, whether or not it is the given Macro. 
Thus, for example the dummy label name AA#SYM in 
this Macro: 


BITEST: MACRO 

* • * 

AAtfSYM: LD 

HL, 

JP 

AA#SYM 


would be assigned the actual label name AA0000 if 
BITEST was the first Macro called in the program. 
The next Macro call would increment this to AA0001, 
and the next to AA0002 , etc. In general do NOT use 
#SYM as the name of a parameter in a Macro 
Definition; the effect of this is that the current 
value of #SYM will be used instead of the desired 
parameter. 

The final point to be made concerning the 
format of the Macro Definition concerns nesting of 
Macros. Macro Definitions may be nested 
indefinitely; this means there can exist a Macro 

Definition which completely contains a Macro 

Definition which completely contains a Macro 

Definition, and so on indefinitely. However, Macro 
Calls may be nested to eight levels maximum. This 
means there can exist a Macro Definition which 
contains a Macro Call, whose Macro Definition 
contains a Macro Call, whose Macro Definition 
contains a Macro Call, and so on up to eight levels 
deep. Exceeding this limit will generate a nesting 
error. Note that a Macro may also call itself, 

provided there is a Conditional way {see IF) of 
ending the self-calling before the ninth level. An 
example of nested Macro CALLS will be found in the 
examples section later in this chapter. 

Some special notes are necessary on nested 
Macro DEFINITIONS. The Assembler does not evaluate 


70 



CROMEMCO MACRO ASSEMBLER 


a Macro Definition within a larger, outside Macro 
Definition until the larger definition is called. 
This means that the outside Macro should be called 
BEFORE the inside Macro to avoid generating a phase 
error. The benefit of nesting Macro Definitions 
may not be obvious; the following example 
illustrates one level of nesting used to define 
several different Macros: 

DEFINE: MACRO #1,#2 

EX#1 #2 : MACRO 

PUSH #1 

PUSH #2 

POP #1 

POP #2 

MEND 
MEND 


This nested definition may then be called in a 
source program as follows: 


DEFINE BC,HL 
START: 

EXBCHL 


The opcode "EXBCHL" was defined by the call to 
DEFINE; other calls to DEFINE could define such 
source code segments as "EXAFBC" or "EXBCDE". 
After the initial call to DEFINE the necessary 
PUSHes and POPs to generate a double register 
exchange will be inserted into the source code by 
the call "EXBCHL" used as an opcode. The DEFINE 
Macro could be resident in a Macro Library to 
further save typing. Note, however, that DEFINE 
must be called once for every Macro which it 
defines and that this call must precede the call to 
the nested Macro . 

The above functions could also have been 
implemented by the single Macro: 
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EXCH : MACRO #1,#2 

PUSH #1 

PUSH #2 

POP #1 

POP #2 

MEND 

The difference here is that the parameters must be 
specified each time the Macro is called. For 
example a Call in a program would be: 


EXCH BC , HL 


Either of the above examples could be used to 
create a Macro to exchange register pairs. Note 
the differences between them. There is a more 
advanced example of nested Macro Definitions in the 
last section of this chapter. 

The above sections describing the details of a 
Macro Definition are provided for reference. 
However, a better feeling for the ways in which 
Macros may be used will come after these details 
are illustrated by means of examples. The last 
section of this chapter provides examples of the 
uses and correct formats of Macro Definitions and 
Calls. The last thing to be described in this 
section is the format of the Macro Call: 

<Label:> <Macro Name> <Pa r ame te r 1 , Pa r ameter 2 , . . . > 

The label is optional; the parameters are also 
optional if none are specified in the Macro 
Definition. That is, the parameters in the Macro 
Call must match those in the Macro Definition in 
number and order; they are NOT, however, preceded 
by the "#" symbol (because these are the actual, 
not the dummy parameters) . The Macro Name should 
match the name appearing in the label field of the 
MACRO statement. At assembly time the Macro will 
be expanded and the source code generated will be 
printed on consecutive lines following the Macro 
Call statement (unless NOGEN is selected — see List 
Options and LIST pseudo- op). Each of these lines 
will have a plus, sign immediately following 

the line number of the print-listing to distinguish 
these lines as belonging to a Macro Expansion. 
Note that Macro Call statements may appear anywhere 
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throughout a source program including within 
another Macro Definition (beware of nesting to more 
than eight levels deep, however) . 

An important point about Macro Calls and 
Definitions is that a Macro must be defined in a 
source program BEFORE it is called. This is to 
prevent a phase error from occurring. The general 
practice is to give all Macro Definitions near the 
beginning of the source code, followed by the body 
of the program itself. One of the most interesting 
features of the CROMEMCO Relocatable Assembler is 
that Z-80 instructions can be redefined (in terms 
of other Z-80 instructions) using Macros. Of 
course, such an instruction which is redefined can 
not be used in its traditional sense again within 
the same source program; however, there are 
specialized cases in which it is desirable to 
slightly modify the function of an instruction. 
Note that the instruction itself cannot be 
modified; it is merely redefined in terms of other 
Z-80 instructions. 

The way ASMB interprets instructions is an 
important part of understanding the Macro 
capability. The Assembler forms a Macro Definition 
Table (MDT) of the Macros residing in the source 
program. This is the first place searched to 
satisfy an opcode. The second place searched is a 
table of addresses specifying the Macros which are 
accessed by the source program and which reside on 
disk (this table is formed ONLY if the Macro = 
option is specified when calling ASMB). If an 
opcode is found in this address table, the required 
Macro Definition is read into memory from the disk 
and added to the MDT. Finally, any still 
unsatisfied opcodes are found in the Z-80 Opcode 
Definition Table (ODT) . Thus, it is possible to 
write an entire source program consisting only of 
Macros. In expanding these Macros, ASMB then uses 
the ODT to evaluate the Z-80 instructions. This 
feature means that ASMB may be used as a language 
compiler by having a library of Macros which 
translate the commands of the language into a 
series of Z-80 instructions. To avoid wasting 
memory and repeating Macros unnecessarily when 
using such a scheme, Conditional Assembly may be 
used in conjunction with Macros to automatically 
generate subroutine calls. This feature, along 
with the other features of Conditional (IF) 
Assembly, are described in the following section. 
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At the end of this chapter is a section of examples 
illustrating some of the features described in 
these first two parts of the chapter. 


Conditional Assembly (IF statements) 


An often close associate of the Macro is the 
Conditional Assembly or IF statement. The IF 
statement allows the user to write a source program 
in which certain blocks of code are assembled or 
not depending on the satisfaction of particular 
conditions. This is especially useful in 
conjunction with the MACRO or *INCLUDE statements. 
When using the IF statement with *INCLUDE, 
particular files may be included or not depending 
on values in the source program. Note that such a 
file may be a series of Macros which are needed in 
the source program only under certain conditions. 
The IF statement is useful with MACRO definitions 
as a means of determining the desired number of 
levels of nesting of a Macro within itself (this is 
illustrated in an example in the following 
section) . The f eat ur e may also be used to cause a 
Macro to set up a subroutine the first time the 
Macro is called, and to generate a subroutine CALL 
upon subsequent Macro calls. The format of the IF 
statement is as follows: 

(no label) IF < 1 1 em > 

Copcodes and 

operands wh i ch 
form the body 
of code to be 
assembled 
cond i t ional ly> 

(no label) ENDIF (no operand) 


The item following the IF may be any legal 
label name , expression, or constant as described in 
Chapter 3. (Note that an ASCII constant must be 
limited to two characters. For example, 'AB' is 
legal, while 'ABC' is not.) It will be evaluated 
by the Assembler to determine whether it is True or 
False; a False expression is one that evaluates to 
0 , and a True expression is one that evaluates to - 
1 (0FFFFH) . However, ANY non-zero value is 
considered to be True. NOTE that the IF statement 
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evaluates the expression as a sixteen-bit quantity. 
If the expression exceeds this limit (for example: 
'0000' is a 32-bit (4-byte) ASCII expression; the 
correct expression is: 0000 or simply 0), it will 
generate an error message. A constant which 
exceeds the range will, however, be evaluated MOD 
65,536 and will generate no error. Note that the 
Expression in the IF statement may use the 
operators described in Chapter 3. All the terms of 
the expression MUST have been previously defined to 
avoid errors; also, the expression must evaluate to 
an absolute quantity. An example of an IF 
statement with an expression is: 

IF COUNT EQ 0 


This will generate a value of True (or -1) if COUNT 
is equal to 0. The example could have been written 
a different way: 

COUNT: DL 1 

* 

* 

IF COUNT 


which will generate a value of True because in this 
case COUNT has the value of 1 which also stands for 
True (non-zero). Note the difference between these 
two examples; in the first case COUNT must equal 0 
for the expression to be True, and in the second 
case COUNT must equal anything but zero for the 
expression to be True. 


After evaluating the expression the Assembler 
will then assemble the code following the IF 
statement if and only if the expression evaluated 
to be True. If the expression was False, the block 
of code bounded by the IF and ENDIF statements will 
simply be ignored by ASMB. It is also possible to 
suppress the print-listing of such ignored code by 
using either the NOCOND List Option or the LIST 
NOCOND pseudo-op (see the appropriate sections for 
more information). An ENDIF statement is required 
for every IF statement in a source program to tell 
the Assembler when Conditional Assembly is 
finished . 


IF statements may be nested up to eight levels 
deep; more than this will generate an error 
message. IF statements may also be nested in 
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Macros; this makes it possible for a Macro to call 
itself a number of times specified by the IF 
statement (an example of this may be found in the 
following section) . Macro parameters may be used 
in the expression of the IF statement. The 
following example to do three rotates illustrates 
this: 

ROTATE: MACRO 
IF 

RRC A 
RRCA 
RRCA 
ENDIF 
IF 

RLCA 
RLCA 
RLCA 
ENDIF 
MEND 


Note that the actual ASCII value of the 
parameter may be specified by enclosing it in 
single quotation marks as with any ASCII string. 
The two IF statements check to see if the parameter 
specified when calling R0TAT3 is "R" or " L” ; if it 
is neither, then no source code is assembled. If 
one or the other, then the corresponding left or 
right rotates will be generated. 


#DIREC 

' #DIREC ' EQ 'R' 


'#DIREC' EQ 'L' 


Exami 


Macro 


Conditional Ass embl ■ 


Many of the features of MACRO and IF 
statements described above are made clearest by 
illustrating them by means of examples. This 
section is included to give the user some idea of 
the many ways in which Macro and Conditional 
Assembly may be used. 


Exam pi e 1 : Block Move Mac ro 

The Macro Definition which follows provides an 
example of the use of a Macro. This Macro defines 
a method for easily generating a block-move of a 
portion of a program: 
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MOVE : MACRO #S OURC E , # SRC END , #DESTIN 

LD H L , #SO URC E 

LD DE , #DESTIN 

LD BC, # SRC END-# SOURCE 

LDIR 

JP #DESTIN 

MEND 


Note that three parameters are expected: a 

starting and ending location for the source, and a 
destination; this is of the same format as the M 
(move) command of DEBUG. Thus, the Macro Call for 
this example might be part of a program such as: 

ORG 2000H 

LOAD: MOVE START, STOP , 1 00H 

START: LD ... 


STOP: END LOAD 


In this example the program would begin 
execution with LOAD, and would move the block of 
code between START and STOP to absolute address 
100H. 


Example 2: 

A Macro that Converts Itself into a Subroutine 

In some cases the in-line coding which results 
from many Macro Calls is undesirable due to memory 
requirements. In such a case a Macro can be 
created which converts itself to a subroutine. 
Such a Macro has both the advantages of a Macro and 
a subroutine. Following is the Definition for 
SUBMAC, a Macro which calls itself: 
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TRUE: 

EQU 

-1 


FALSE: 

EQU 

0 


FIRST: 

DL 

TRUE 


SUBMAC: 

MACRO 

IF 

NOT FIRST 



CALL 

SUBROT 



ENDIF 

IF 

FIRST 


FIRST: 

DL 

FALSE 



JP 

DONE ; 

causes program to jump around 

SUBROT: 

i • * 

■ 

t 

subroutine upon first call 


RET 



DONE: 

NOP 

ENDIF 

MEND 

t 

program jumps here 


The first three lines above are not part of the 
Macro Definition, but the value of FIRST must be 
initialized before it is used in the Definition. 
The JR DONE instruction in the above is used to 
cause a jump around the subroutine when it is 
assembled in-line with the source upon the first 
Call to SUBMAC. A sample program which might use 
this Macro i s : 

START: 

SUBMAC 

SUBMAC 

END START 


The first Call to SUBMAC above would generate 
the subroutine itself in-line. After the first 
call the value of FIRST has been redefined to be 
FALS £; hence, the second Call to SUBMAC would 
generate simply the line: CALL SUBROT. 


Example 3: 

Nested Macro Definitions to Generate 
Rotate Instructions 

A number of interesting and useful functions 
can be implemented by using nested Macro 
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Definitions or Calls, 
example , making use of 
Definitions to define a 


The following is one such 
one level of nested Macro 
number of different Macros: 


ROTATE: MACRO 
M#SHFT : MACRO 
VALUE: DL 

#SHFT 

IF 

M # S HF T 
ENDIF 
MEND 
MEND 


#SHFT 
#NUM , #REG 
#NUM-1 
#REG 

VALUE NE 0 
VALUE, #REG 



Th 

e Mac 

ro 

ROTATE 

may 

numb 

er 

of sh 

ift 

and rotate 

inne 

r Macros 

are 

not de 

fined 

call 

ed 

one t 

ime . 

Thus 

, at 

prog 

ram 

in which 

we wi sh to 

nece 

ss a 

ry to 

ini t 

i al i ze 

th em 


b e 

used 

to defii 

ne a 

Mac 

ros ; 

however , 

the 

un t 

il ROTATE has 

been 

the 

beg i 

inning of 

the 

use 

the 

Macros, i 

t is 

by t 

he Calls: 



SETUP: ROTATE SRA 

ROTATE RRC 
ROTATE RR 
ROTATE SRL 
ROTATE RLC 
ROTATE RL 
ROTATE SLA 


Note that this will define 7 additional Macros with 
the names MSRA through MSLA. The M (or any other 
legal character) is necessary in order to avoid 
having the Mac ro names match Z-8 0 opc odes . {No te 
that these same Z-80 opcodes are used within the 
Macro Definitions.) We can now call any of these 
Macros, giving a number and a register as 
parameters : 


START 


LD 

MSRA 

MRLC 

MRR 

END 


4, A 
8, B 
3 , E 
START 


The number 
number of shi 
generated. Thus 
when expanded, g 


in each of the above case 
fts or rotates wh i c h 
, the Macro Call "MSRA 4, 
enerate 4 "SRA A" instruc 


s is the 
will be 
A" will, 
tions in 
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the source code. Since the ROTATE Macro could be 
contained in a Macro Library, the user's source 
program could contain a Macro Call of this type. 
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CHAPTER 6: ASSEMBLER ERROR MESSAGES 


1 The Assembler generates a number of error 

messages while assembling to inform you of its 
progress. These messages fall into two general 
classes: those that involve the actual call to 
ASMB, are generated shortly thereafter, and are 
sent to the console; and those that are generated 
while the source code is being assembled and which 
inform the user of incorrect structures in the 
code. These two classes are described below. The 
user should note that in most cases the Assembler, 
when encountering an error, will assemble the line 
such that the correct number of bytes are reserved. 
Thus, the addresses are still numbered correctly, 
and the program may be loaded into memory and the 
incorrect bytes changed using DEBUG. This saves 
reassembling a very long program when the user 
plans to debug it anyway. Of course, in the final 
version of source code, the error should be 
corrected . 


Error Messages Generated Fol 1 owi ng a Call to ASMB 


The following is a list of error messages, 
followed by a brief description of their meanings. 
Note that the errors are printed exactly as they 
would be sent to the console, upper or lower case. 
All the errors described in this section will ABORT 
the assembly and ret urn control to CDOS . The user 
should be aware that any temporary files created by 
ASMB will remain on the disk following an abort; 
these may be erased if desired, but this is not 
required if the error is fixed and the file 
r eassembl ed . 
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source file not found 

This is generated when ASMB cannot find the 
specified source file on the disk. Check your 
spelling of the filename and the disk directory for 
the file. 


no directory space 

This is generated when ASMB attempts to open an 
output file (.REL or .PRN, for example) and finds 
that there, are already 64 entries (the maximum 
allowed by CDOS) on the disk. This is NOT the same 
as running out of disk space (see following error 
message). There may be 64 directory entries which 
are all short files, and thus not all the available 
kilobytes may be used (81 Kbytes for small and 241 
Kbytes for large disks) . 


write error, file - <f il ename . ex t> 

ASMB will open any files which it requires (.REL or 
.PRN files, or the temporary files it opens to 
manage the XREF and OPCODE listings), shortly after 
being cal led . This me ssag e is generated if the 
disk is full (81 Kbytes for small, 241 Kbytes for 
large) when these files are opened, or if a file 
being written to causes the disk to become full 
during assembly. 

Note: The temporary files for XREF and OPCODE 

listings are created only if one or both of these 
options are specified. The XREF file is named 
< f i 1 en am e > . $ $ $ and the OPCODE file is named 
< f i 1 en am e > . $ $ 0 , where <filename> is the one 
specified in calling ASMB. These files are created 
during Pass 1 of the Assembler; they are removed 
from the disk following completion of the assembly. 


selected disk error 

This message is generated if the 3-letter 
d r ive- reque st instruction given after the filename 
is incorrect, i.e., if it specifies a drive which 
does not exist or is not one of the characters, "X" 
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or "Z". An exam pi e which will generate this 
message is: ASMB TES TFI L E . AB E . " E" is not a 
correct drive letter. 


invalid option 

This message is generated if an invalid or 
misspelled Option is specified following the 
<filename> in a call to ASMB. This will also 
appear if an invalid delimiter (such as is 

used between Options. One or more <space(s)> is 
the only valid delimiter to separate Options. 


MACRO library not found 

This is generated only if the 
Mac ro=<d : f il en ame . ex t> option has been issued and 
the filename cannot be found by the Assembler on 
the specified drive. 


MACRO library file error 

This error will abort assembly of the source 
program. The error message is printed to the 
console as shown above. It is caused by the 
Assembler encountering a MEND statement with no 
matching MACRO definition statement in the source 
code preceding it ONLY FOR THE MACRO LIBRARY if one 
has been specified. On the other hand the "no 
matching MACRO" message is printed if this 
condition occurs with a MACRO present in the SOURCE 
file and will NOT abort assembly. The primary 
reason for the addition of this error message is to 
inform you of mistakes in a MACRO library before 
assembly occurs so that you will have the 
opportunity to change it using EDIT. 


out of memo ry 

The Assembler program (ASMB.COM) is loaded 
into memory at 100H and begins execution there. 
Above itself in memory ASMB forms the symbol table, 
which grows upward. Above the symbol table but 
below CDOS ASMB forms the Macro Definition Table 
(MDT) , which grows downward through memory. If a 
user-program being assembled contains a great 
number of Macros and/or symbols, the symbol table 
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and the MDT may grow together, thus generating the 
Tl out of memory" error. The message will be printed 
on the console and assembly will be aborted at this 
point. The simplest solution to the problem if it 
occurs is to edit the source code into two or more 
separate modules, assemble them separately, and 
link them at run time. 


Error Messages Generated During Assembly 


The following list contains the error messages 
generated during assembly of source code. They 
inform the user of a wide range of incorrect 
specifications such as misspelled opcodes or 
invalid relative jumps. When an error occurs, ASMB 
prints the error message which applies on the line 
immediately following the error. The message is a 
complete expression, not a symbol, and it occupies 
the entire line in a pr in t- 1 i s t i ng , 

It is set off by being preceded and followed 
by a string of asterisks. If the pr in t- 1 i st ing is 
sent to the disk or is not generated at all, any 
errors occurring during assembly will still be 
printed on the console; in this case the entire 
line of code as generated in the listing along with 
the error-type will be printed. Following assembly 
the total number of errors will be printed. Also, 
at the end of the listing will be printed a s ummary 
of all the line numbers where errors have occurred 
during assembly* This summary is printed (either 
to the disk or to the console) in the form of a 
table; the Width™ option will limit the length of 
lines of characters in this table, but will not end 
any line in the middle of an entry just as was the 
case with the cross reference tables. Note that 
for each type of error message up to 100 entries 
will be printed in this table. The error summary 
table is a very useful feature for going back and 
editing the file for corrections. Below in 
alphabetical order are the error messages which may 
appear along with a brief explanation of each one. 
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instruction not allowed 

This error message will be printed to the 
console and the pr in t-1 i sting during assembly but 
will not abort assembly. The error message will be 
printed on the console exactly as shown above, but 
ONLY if the HEX or HEX= option has been specified 
in calling ASMB. It will follow one of these 
pseudo-ops : 

COM DATA REL 

ENTRY EXT or EXTRN NAME 


because these apply to several aspects of 
RELocatable code, which is not produced under the 
HEX option. Note that for the DATA, REL, and NAME 
pseudo-ops this error message may be treated as a 

there will be no effect on the .HEX 
to its occurence. However, if the 
f o 1 1 owi ng the COM , ENTRY , o r EXT 
the original source will have to be 
re-edited to change these lines and any references 
to label names appearing under them. 


warning because 
output file due 
message occurs 
pseudo-opcode s , 


a rg ument error 

This arises when an invalid constant is used. 
This might happen when a number is incorrect for 
its base, or when an ASCII character string is too 
long for an expression. For example, the lines: 

LD A,108Q (3 not valid octal character) 

LD HL, 'ABC' (too many ASCII chracters) 

will both generate arg ument errors. 


divide by zero error 

This arises when an evaluated expression 
involves an attempt to divide by zero. An example 
is : 

END: EQU 0FFF8H 


LD HL,255/ (END+8) 
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Since the value of END+8 is 0 , this would produce 
the divide by zero error. 


expression error 

This applies to operand expressions which 

involve certain illegal operations with labels 
belonging to REL, DATA, or COM code segments. 
Expressions involving relocatable labels are 
limited to the following operations: 

RELNAM+ABSNAM ( relocatable} 

RELNAM-ABSNAM (relocatable) 

RELNAM-RELNAM (absolute) 

where RELNAM stands for a label belonging to a 
relocatable code segment and ABSNAM stands for a 

label belonging to an ABS code segment (see REL and 
ABS in the chapter on pseudo-ops) . The type of 
expression of the result of the given operation is 
given to the right in parentheses. Also note that 
in the last case above both RELNAMs must belong to 
the same type of Code Segment or an error will also 
be generated. (For example a label belonging to a 
COMmon area may not be subtracted from a label 
belonging to a REL area.) An expression error is 
generated if any arithmetic is attempted (i.e., an 
expression is formed) using EXTernal names, as the 
values of these are unknown to the Assembler. This 
does not mean that EXTernals may not be used as 
operands, of course. Relative jumps from one type 
of Code Segment to another will also generate 
expression errors; for example it is illegal to 
jump from a REL to a DATA area using a relative 
jump. The reader should refer to the section of 
Chapter 3 on operators for more information on the 
use of expressions. 


file not found 

This message is printed following an INCLUDE 
for which the file to be included cannot be found 
on the disk. This error does not terminate 
assembly, but further errors may be generated if 
the source code looks for labels belonging to the 
missing file. Note the difference between this 
message, which is printed in the listing, and the 
"source file not found" and "MACRO library not 
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found" messages which abort assembly and are 
printed on the console. 


label error 

This arises when a label contains or begins 
with an illegal character. The characters 0-9 are 
legal within a label but are illegal as the FIRST 
character. Allowable characters for labels are A- 
Z, a-z , " . " , and All register names are also 
illegal as labels; these are listed in Chapter 3 
under the section on labels. 


label not allowed 

The following list of pseudo-ops do not ALLOW 
labels to precede them because of their nature. 
This message is printed if a label is used before 
one of the following pseudo-ops: 


ABS 

FORM or 

EXT or 

MEND 

COM 

EJECT 

EXTRN 

NAME 

DATA 

ENDIF 

IF 

REM 

REL 

ENTRY 

LIST 

TITLE 


Note that this is NOT the error message which 
is printed in the case of an illegal character in a 
label (see "label error"). Although the "label not 
allowed" message is printed and counted as an 
error, the source code will still be assembled 
correctly and the incorrect label will be ignored 
by ASMB. 


missing label 

This message is printed when the following 

pseudo-ops are NOT preceded by a label: EQU and 

DEFL or DL. This is opposite to the above case 

(see "label not all owed " ) ; note that these two 
pseudo-ops REQUIRE a label to be assembled 

correctly. A MACRO definition section of code also 
requires a label in order to be used by the 

Assembler. For more information on Macros see the 
chapter devoted to them. 
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multiple definition 

This message occurs any time a data or program 
label is defined more than once. This is prone to 
happen when using INCLUDES, as the included file 
may contain a label also used in the source file. 
Simply re-edit one of the files and change the 
label { s) involved . 


multiple MACRO definition 

This error is exactly similar to the "multiple 
definition" above, but is caused by a multiply- 
defined Macro name. 


nesting error 


This message appears whenever INCLUDES, 
MACROS, or IFs are nested beyond the levels allowed 
by the Assembler. These are: 8 levels of nesting 

for MACROS and IFs, and 4 levels of nesting for 
INCLUDES. Note that this means 8 levels of nesting 
for Macro CALLS; Macro DEFINITIONS may be nested 
indefinitely. However, be sure, when nesting Macro 
definitions, to insert the correct number of MEND 
{Macro END) pseudo-ops; the Assembler might 
otherwise consider a portion of the source code to 
be part of a Macro. Examples of both nested Macro 
calls and definitions appear in the chapter on 
Macros . 


no matching IF 


This 
pseudo-op 
in the source 


message appears following 
which has no corresponding IF 
code pr eced i ng it. 


an END IF 
statement 


no matching MACRO 


This 
op which 
sta temen t 


message appears following a MEND pseudo- 
has no corresponding MACRO definition 
in the source code preceding it. 
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opcode er 

ror 





This foil 

ows 

an 

opcode 

wh i ch 

is illegal; 

this 

may 

be because 

it 

i s 

mi sspe 1 

led or 

because 

the 

user 

int 

ended for i 

t to 

be 

a Macro and 

forgot to 

i nc 

1 ude 

thi 

s Macro def 

ini t 

ion 

m 






phase error 

This error message follows a line containing a 
name which was defined differently between Pass 1 
and Pass 2 of ASMB. The most common cause of this 
is that a label has been used as a value (such as 


in an EQUate statement) 
An example is: 

be fore it has 

been defined. 

LABE LI : 

EQU 

LABEL2 


LABEL2 : 

LD 

A, 5 


LABEL2 has been used in 
was defined- The error 
offending statement 

the EQU statement before it 
is corrected by moving the 
(in this case the EQU 


statement) to follow the label definition. Other 
causes of phase errors are (1) using a term in an 
expression in a DS or IF statement which has not 
been defined yet, and (2) calling a Macro before it 
has been defined. 


range error 

This message follows a relative jump which 
exceeds the range allowed for such jumps. This 
range is -126 bytes to +129 bytes measured from the 
address at which the relative jump is 1 oca ted ; the 
actual values generated by the Assembler are in the 
range -128 to 127 because the Z-80 measures 
relative jumps from the instruction following the 
j ump. 

The Assembler requires an AD DR ESS, usually 
specified by means of a label, to be used as the 
operand of a relative jump instruction. ASMB then 
calculates the relative displacement of the jump 
and places this value in the object code. Remember 
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that if a number is used, it will be considered to 
be an absolute address, NOT a displacement. Note 
that this may be different from the description of 
relative jumps in the Z-80 manuals by Mostek and 
Z i 1 og . Some examples will illustrate these 
concepts ; the statement : 

JR NZ , 1 00 

tells A SMB to generate a relative jump to LOCATION 
100 or 64H, NOT to jump relative to the present 
location by 100 bytes. To avoid this confusion a 

better form would be: 

JR NZ, LABEL 

LABEL: LD A, 3 


for which ASMB will calculate the correct jump no 
matter where LABEL happens to be located. 
(However, if the label belongs to another type of 
Code Segment, an expression error will be 
generated; for example it is illegal to jump from a 
REL area to a DATA area using a relative jump.) 


syntax error 

This error message covers a wide range of 
ills; it generally appears when a quantity in one 
of the four Assembler Fields (see Chapter 3) has 
been misused. For ex am pi e, writing a remark 
without preceding it with a on a line which 

already contains a label, opcode, and operand will 
produce a syn tax error. If you don't know the 
cause of the message, look up the expression or 
opcode of which you are unsure. 


too many COMmons 

This message follows the use of more than the 
allowable number of COMmons. ASMB allows a total 
of 15 COMmons including one "blank” COMmon. The 
term blank COMmon means that one of the COMmons 
need not be named , not that there is nothing in it. 
See the COM pseudo-op for more information on their 
use . 
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undefined symbol 

This message follows a line containing a label 
name in the operand field which has not been 
defined. This is one of the most common of 
assembly language mistakes: using a label name for 
a data quantity and then forgetting to define it. 
Labels are defined by appearing in the label field 
of any opcode or pseudo-op which allows labels. 


value error 

This message follows a line in which a value 
is used which exceeds the range allowable for the 
opcode used. This value may be a constant or an 
expression. Opcodes which expect one-byte 
quantities will generate a value error for any 
expression whose value exceeds the range 0 to FFH 
(or its equivalent representation in decimal, 
octal, or binary). Opcodes which expect two-byte 
quantities will not generate an error if the value 
simply exceeds the numeric range (65,535); the 
value will simply "wrap around". That is, a value 
of modulus 65,536 is returned without an error 
flag. Some examples will illustrate these ideas. 

The following will generate a value error: 

LD A,3000H(a two-byte quantity used as one byte) 

However , the line 

LD HL, 70000 

will not generate a value error; instead, the value 
4464 or 117 0H (which is 70000-65536) will be 
generated . 


Va 1 ue 

errors will also 

be 

generated 

by the 

BIT, SET, 

a nd 

RE'S opcodes 

if 

the value 

of the 

ex pr ess i on 

used 

as an operand 

is 

outside the range 

0 through 7 

» 
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CHAPTER 7: ASSEMBLER PRINT-LISTINGS 


Following is the print-listing which results 
from the assembly of the example in Chapter 1 
("Getting Started") . There is much valuable 
information in this listing; it is therefore given 
here in a separate chapter so that the various 
terms and symbols can be explained. The command 
line which was typed to produce this assembly is 
slightly different from the command line typed in 
Chapter 1. This is because several Assembler 
Options have been specified here so the user can 
see what type of listing they produce. The command 
line which was typed to produce the following 
assembly is: 

ASMS TIMER SYMB XREF OPCODE RANGE 

The SYMB option requests a Symbol Table, XREF 
and OPCODE request Symbol and Opcode Cross 
Reference Tables, and Range requests those absolute 
jumps which are within range to be relative jumps. 
The next four pages contain the listing that 
results from this assembly. Following that is an 
explanation of the terms and conventions used in 
the listing . 
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CROMEMCO CDOS Z80 ASSEMBLER version 02.02 


PAGE 0001 




0001 

; This 

program 

rings the console bell at approximately 



0002 

; half-second 

intervals determined by a timer loop. 



00 03 

J 





(0007) 

0004 

BELL: 

EQU 

7 j 

console bell is ASCII 07 


(0002) 

0005 

WRITE: 

EQU 

2 

write character to console 


(0005) 

0006 

CDOS: 

EQU 

5 j 

use system call to write 


( 0 2FF) 

0007 

TIMIT: 

EQU 

2FFH ; 

2 is no. of half-seconds; 



0008 

t 



FF (256) is no. of loops 


(00FF) 

0009 

DURAT: 

EQU 

0FFH 

FF (256) is loop duration 



0010 

t 






0011 

; Main 

Program 





0012 

f 




0000 ' 

315A00 ' 

0013 

START: 

LD 

SP, STACK 

initialize stack pointer 

0003 ' 

01FF02 

0014 

LOOP: 

LD 

BC, TIMIT 

B is no. of half-sec.; 



0015 

l 



C is no. of loops 

0006’ 

3EFF 

0016 

TIM2 : 

LD 

A, DURAT 

get duration (256) 

0008 ' 

3D 

0017 

TIM1 : 

DEC 

A 

decrement and 

0009 ' 

2 0FD 

0018 


JR 

NZ,TIM1 , 

loop til zero 

000B 1 

0D 

0019 


DEC 

C 

decrement loop counter 

000C' 

20F8 

0020 


JR 

NZ ,T IM2 

until zero 

000E ’ 

1 0F6 

0021 


DJNZ 

TIM2 j 

r countdown half-seconds 

0010 1 

1E0 7 

0022 


LD 

E , BELL 

; set-up to ring bell 

0012 ’ 

0E02 

0023 


LD 

C, WRITE ; 

; set-up to write console 

0014 1 

CD0500 

0024 


CALL 

CDOS 1 

: call system 

0017 1 

C30300 * 

R 0025 


JP 

LOOP ; 

; loop and repeat 



0026 

r 






0027 

; Stack 

Area 





0028 





0 0 1 A ’ 

(0040) 

0029 

BOTTOM: 

DS 

40H 

; allow 64 bytes for stack 


( 00 5A 1 ) 

0030 

STACK: 

EQU 

$ : 

: current location counter 



0031 

F 



equals top of stack 

005A' 

(0000 1 ) 

0032 


END 

START 


E r ro 

rs 

0 





Range 

Co unt 

1 






Parity Count 0 

Program Length 025A (90) 
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CROMEMCO CDOS Z80 ASSEMBLER version 02.02 
SYMBOL TABLE 


PAGE 0002 


BELL 0007 BOTTOM 001A' CDOS 
STACK 00 5A ' START 0000' TIM1 
WRITE 0002 


0005 
0008 ' 


DURAT 

TIM2 


00FF 
0006 ' 


LOOP 

TIMIT 


0003 ' 
02FF 
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CROMEMCO CDOS Z80 ASSEMBLER version 02.02 PAGE 0003 

CROSS REFERENCE LISTING 


BELL 

0004 

0022 

BOTTOM 

0029 


CDOS 

0006 

0024 

DURAT 

0009 

0016 

LOOP 

0014 

0025 

STACK 

0030 

0013 

START 

0013 

0032 

TIM1 

0017 

0018 

TIM2 

0016 

0020 0021 

TIMIT 

0007 

0014 

WRITE 

0005 

0023 
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CROMEMCO CDOS Z80 ASSEMBLER version 02.02 PAGE 

OPCODE CROSS REFERENCE LISTING 


CALL 

0024 





DEC 

0017 

0019 




dj nz 

0021 





DS 

0029 





END 

0032 





EQU 

0004 

0005 

0006 

0007 

0009 0030 

JP 

0025 





JR 

0018 

0020 




LD 

0013 

0014 

0016 

0022 

0023 


0004 
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Th i s 

columns or 
Column 1 - 


Col umn 2 - 


Column 3 - 

Column 4 - 


Li st i ng Co 1 umns 


listing is divided up into a number of 
fields. These are described below. 

This is a 16-bit address printed in 
hex. If an absolute ORG statement has 
not been given, the addresses will 
start with 0. Since the modules are 
relocatable, however, the subsequent 
addresses are only relative to the 
final program base when the program has 
been loaded. Immediately following the 
address is either a space or one of the 
symbols: ' , ", or *. These are 
described below. 

If the statement is a pseudo-op which 
generates a value (for example, the EQU 
statement), that value will be printed 
here in parentheses. For all Z-80 
opcodes this column will contain up to 
four bytes of object code in hex. The 
DB and DW pseudo- ops will also produce 
object code in this column . If the 
code being assembled is relocatable, 
all addresses will correspond to 
relocatable addresses in column one, 
NOT the actual ad dresses these bytes 
will have when the program is linked 
and loaded into memo ry . Relocatable 
addresses will be followed by one of 
the symbols: ", *, or f, described 

below . 

This column is usually not printed. If 
the Range Option has been specified, 
all absolute jumps which are within 
range to be relative jumps are marked 
with an "R" character in this column. 

This column contains the line numbers 
of the source code in decimal beg inning 
with 0001. All lines will be numbered 
including those containing only 
r emarks . 
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Column 5 - This is the label field of the original 
source. See Chapter 3 of this Part for 
a complete description. 

Column 6 - This is the opcode field of the 

original source. See Chapter 3 for a 

complete description. 

Column 7 - This is the operand field of the 

original source. See Chapter 3 for a 

complete description. 

Column 8 - This is the remark field of the 

original source. See Chapter 3 for a 

complete description. 


Lines o £ Listi ng 


The listing also contains useful information 

on the lines printed out at its beginning and end. 

These are described below. 

Beginning, Line 1 - This line contains the 

heading of the listing giving the 
current version and release numbers of 
ASMB. Also on this line is the page 
number; listings are numbered 
consecutively in decimal including the 
symbol and other tables at the end . 

Beginning, Line 2 - This line will contain the 

t i tl e of the modul e being assembl ed if 
the user specified one using the TITLE 
pseudo-op. A blank line is inserted if 
no title is used. The Assembler also 
inserts a blank line just before the 
listing beg ins on every page . 

Interspersed Lines - Error messages occupy one 

full line of a listing and are printed 
immediately following the line in which 
the error was first detected. 

End of Listing, Line 1 - The total number of 

errors which occur r ed d ur i ng Assembl y 
is printed on this line. 
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End of Listing, Line 2 - This line will be 

printed only if the Range Option has 
been specified, and it gives the total 
number of jumps marked by Range. 

End of Li sting, Line 3- This line will be 

printed only if the Parity Option has 
been specified, and it gives the total 
number of 8080-280 conflicts found (see 
Parity Option in Chapter 2). 

End of Listing, Line 4 - This gives total 

program length (i.e., the byte-count of 
the object code) in both hex and in 
dec imal . 

End of Listing, Line 5 - This and the 

following lines list all those COMmons 
which have been defined in the module 
along with their lengths in both hex 
and in decimal. Up to 15 COMmons may 
be listed. 


Listing Symbols 


There are four symbols which appear throughout 
a print-listing which give some additional 
information. These are described below. 

Single Quotation Mark (') - This symbol 

follows all addresses (column 1) which 
belong to a REL area. The s ymbol also 
follows all references to REL addresses 
made in the object code. For example 

the three bytes: 

C31F00 1 

in the object code mean to jump to 

address 001F of the REL segment of 
code . 

Double Quotation Mark (") - This symbol 

follows all addresses (column 1} which 
belong to a DATA area. The symbol also 
follows all references to DATA 
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addresses made in the object code. 
Remember that DATA program segments are 
very similar to REL program segments. 

Asterisk (*) - This symbol follows all 

addresses (in column 1} which belong to 
a COMmon program segment. The symbol 

also follows all references to COMmon 

addresses made in the object code. 

Pound Sign (#) - This symbol appears only 

following an address in the object 
code, and marks those lines as ones 

referencing EXTernals, The address 
just preceding the pound sign is the 
location that that EXT was last 
referenced, or is 0000 if it's the 
first time in the module that the EXT 
i s referenced . 

Note that addresses in column 1 or in the 
object which are not followed by one of the four 
symbols above belong to an ABSolute segment of 
code . 


Tables Fol lo wi ng the Listing 


There are several tables which may follow the 
print-listing of the source code. These are 
described briefly below. 


Symbol Table 


The symbol table contains an alphabetical list 
of all the symbols (labels) defined in the source 
program. Each symbol will be followed by its value 
and one of the four symbols described above to tell 
the user to which program segment it belongs. The 
value will be either the address at which the 
symbol is defined or the value of the expression to 
which it equates. Note that EXTernals listed in 
the symbol table do not follow this rule. The 
address listed following an EXT name is the address 
of its first occurrence in the source. 
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Cross Reference Table 


The cross reference table contains an 
alphabetical list of all symbols and the line 
numbers of both their places of definition and 
occurrence throughout the source program. The 
symbols are listed in the first column, the line 
numbers of their definition in the second column, 
and the line numbers of their occurrence are listed 
by rows to the right of the first two columns. 
Symbols which have been multiply-defined by the use 
of DL statements will have the line numbers of 
subsequent definitions listed to the right and 
followed by the pound sign (#). 


Opcode Cross Reference Table 


The opcode cross reference table contains an 
alphabetical list of all opcodes and Macro names 
along with the line numbers of their places of 
occurrence (and places of definition for Macros). 
The opcodes or Macro names are listed in the first 
column, the line numbers of Macro definitions ONLY 
are listed in the second column, and the line 
numbers of their places of occurrence are listed by 
rows to the right. 

This completes the description of the items 
which make up an assembled print-listing. This 
also completes Part I of this manual. 
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CHAPTER 1: USING THE CROMEMCO LI MKER/LOADER 


Command Format 


The CROMEMCO Linker/Loader is used to link 
assembled program modules together, load them into 
memory, and begin execution there if desired. The 
Linker is supplied to the user on diskette (large 
or small) under the directory entry "LINK.COM". 
The command line to call LINK consists of a number 
of filenames and switches according to the 
following format: 

LINK <d:filenaml.ext/s,d:filenam2.ext/s, ...> 

where d stands for the disk drive letter (A through 
D) , s stands for one of the legal switches of the 
Linker (see list in this chapter), and filen ame .ext 
stands for a user filename plus its 3-letter 
extension. The only quantity required above after 
the word LINK is filenaml. LINK defaults to the 
current drive if the disk drive letter is omitted, 
and it defaults to the extension .REL if the 3- 
letter extension is omitted. The switches are not 
necessarily required, and are used to give LINK 
instructions regarding the files. The Linker will 
accept commands in the order received, but does not 
require a single command line. The prompt for LINK 
is an asterisk, any time the asterisk appears, 

a command may be entered. Thus, the names of files 
to be linked may be given one at a time rather than 
on one command line. The example of Chapter 4 will 
illustrate this further. After each line is typed, 
LINK will load or search the named file(s). When 
LINK finishes this process, it will list all 
symbols that remain undefined followed by an 
asterisk. 

The switches LINK accepts give the user a 
variety of ways to control the linking process. 
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For example the user may cause the Linker to search 
special library files to satisfy undefined globals 
by linking the filename to be searched followed by 
/S. The /M switch can be used to map a list of all 
defined and undefined symbols. These switches are 
described in the next section. Chapter 2 gives a 
brief explanation of the operation and format of 
LINK and associated .REL files for those who are 
interested. It may be safely skipped, however, for 
it contains no information on the actual use of the 
Linker. Chapter 3 is a brief summary of the error 
messages that occur and why, and Chapter 4 gives a 
step-by-step example of the process of linking and 
load i ng program mod ul es . 


LINK Switches 


The Linker all ows a number of switches which 
specify actions affecting the loading process. 
These switches are listed here: 


E (Exit to CDOS ) 

Exit to CDOS upon completion of link and load. 
Prior to exiting, LINK prints on the console the 
start and stop execution addresses along with the 
number of 256-byte pages of memory the program 
occupies (in decimal), according to the following 
fo rma t : 

[xxxx yyyy zz] 

where xxxx is the address at which execution will 
start, yyyy is one more than the hiqhest location 
used by the loaded object code, and zz is the 
decimal number of pages required. 

If it is desired after executing the /E to 
save the file now located in memory, this can be 
done using the SAVE command, which is one of the 
CDOS intrinsic commands (see also CDOS manual). 
The user would then type: 

SAVE filename. ext zz 

where zz is the same number printed out by LINK 
above (following the issue of /E) . The filename 
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can be any legal name; however, if the name used 
already resides on the disk, the saved file will be 
written over this existing file. The 3-letter 
extension is frequently .COM because this procedure 
is often used to create command files; however, any 
extension may be given. Note that other CDOS 
INTRINSIC commands may be given before the SAVE 
command; for example, DIR may be typed to see about 
available directory space. However, executing any 
EXTRINSIC commands (XPER, EDIT, etc.) will change 
the contents of the user-area. For a 32K system, 
zz=105 will save the entire user-area. 


G (Go - start execution) 


Start execution of the program as soon as the 
current command line has been interpreted. Prior 


to execution, LINK 
and stop addresses 
occupied by the 
format shown above 
message " [BEGIN 


prints on the console the start 
and the number of 256-byte pages 
object code, according to the 
(see / E ) . Following this is the 
EXECUTION]" at which point 


execution is started by LINK, 
initializes the stack pointer at 
address of the user-area in case this 
forgotten by the user program. 


The Linker 
the highest 
operation is 


M {Map all symbols) 

List both all the defined globals and their 
values and all undefined globals followed by an 
asterisk. The map may be sent to the printer by 
typing Control-P (~P) following the LINK command 
line. This printed map of symbols is very useful 
for debugging the user-program. Once the object 
code has been loaded into memory by LINK, /E can be 
issued and the correct portion of the user- area 
SAVEd in a file. Then the program DEBUG can be 
called and used to load and debug the file just 
created. The global map printed previously can be 
used to reference addresses. 
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R (Reset linker) 

Put Loader back in its initial state. /R is 
used to restart LINK if the wrong file was loaded 
by mistake. /R will take effect as soon as it is 
encountered in a command string. 


S (Search file) 

Search the disk file having the filename 
immediately preceding the /S in the command string, 
to satisfy any undefined globals. This is 
convenient for having the Linker search a library 
file of much-used routines. (Note that when using 
LINK with CROMEMCO FORTRAN, the library file 
FORLIB.REL is searched automatically to satisfy 
undefined globals.) 


U (list all Undefined globals) 

List all undefined globals as soon as the 
current command line has been interpreted and 
executed. LINK defaults to this switch; therefore, 
it is generally not needed unless it is desired to 
reproduce this list more than once. For example 
say that during link the list of undefined globals 
is printed to the console. The user could then 
type Comtrol-P followed by "/U" to cause the 
undefined globals to be listed a second time, this 
time to the printer as well as the console. 
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CHAPTER 2: FORMAT OF LINK -COM PAT IBLE OBJECT FILES 


The following is a description of the format 
of .REL files which are to be compatible with the 
CROMEMCO Linker. This information is provided for 
the interested programmer, but is not in any way 

required reading for the person learning how to USE 
the Linker. 

LINK compatible object files consist of a bit 
stream. Individual fields within the bit stream 

are not aligned on byte boundaries except as noted 
below. The use of a bit stream for relocatable 

object files keeps the size of the files to a 

minimum, thereby decreasing the number of disk 
reads and writes. The first bit of a field is 
either a one or a zero, and this is followed either 
by an 8-bit byte or a 2-bit field hav ing the 
following meanings: 

Mean i ng 

load the following eight-bit byte as absolute code 

read in the following two bit field: 

11 Add sixteen-bit offset to common base 
10 Add sixteen-bit offset to data base 
01 Add sixteen-bit offset to program base 
00 Special LINK item 

Special LINK item fields begin with the bit 
stream 100 as just explained. This is followed by 
a four-bit control field, an optional A- field which 
consists of a two-bit code specifying address type, 
and an optional B-field which consists of 3 bits 
g iv i ng a s ymbol length. The 2 -bit address type has 
the same meanings as the 2-bit field above except 
00 specifies absolute addressing. The 3-bit symbol 
length is followed by eight bits for each character 
of the symbol. We can represent this bit stream by 
the fo 1 1 owing : 


Bit 

0 

1 


A~f i eld 

1 00 xxxx <yy two-byte-value> <zzz 
where the spaces in the above 


B-field 

char acte r s-o f-symbo l-name> 
show where the 
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various fields end, the angular brackets denote 
optional quantities, and where 

xxxx is the four-bit control field 
yy is the two-bit address type field 
zzz is the three-bit symbol length field 

The two-byte-value following yy will be either 
the 16-bit offset specified or the absolute 
address, and the characters-of-symbol-name 
following zzz will be in ASCII, each character 
occupying eight bits. 

The four-bit control field will specify the 
operation or function of the bit stream. It can 
have the following values, where the four-bit value 
is given in the left-hand column in decimal: 

(The following LINK items have a B-field only) 

0 Entry Symbol (name for search) . 

1 Select COMmon Block. 

2 Program Name. 

3 Reserved for Future Expansion. 

4 Reserved for Future Expansion. 

(The following LINK items have both an A-field and a B-field) 

5 Define COMmon Size. 

6 Chain External (A is head of address chain) . 

B is name of external symbol. 

7 Define Entry Point. 

8 Reserved for Future Expansion. 

9 Reserved for Future Expansion. 

(The following LINK items have an A-field only) 

10 Define Size of Program Data Area. 

11 Set Loading Location . 

12 Chain Address. 

A is head of chain; replace all entries in chain with 
current location counter. The last entry in the chain 
has an address field of absolute zero. 

13 Define Program Size. 

14 End Program (forces to byte boundary) . 

(The following LINK item has neither an A- nor a B-field) 

15 End of File. 
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CHAPTER 3: LINK ERROR MESSAGES 


The Linker gives several error messages in 
case of an illegal operation. These are listed 
below in the summary along with an explanation of 
each one. Note that there are two types of error 
messages: fatal errors and warnings. Fatal error 
messages are preceded by question marks {?) and 
warning messages are preceded by percent signs {§). 
A program will run in some cases when a warning has 
been issued; however, it is better practice to 
correct the error and link again. 


Fatal Errors 

?No Start Address A /G switch is issued, but no 

main program module has been 
loaded . Remember when creating 
and linking machine lang uag e 
programs that the main mod ul e 
must have an address or label 
in its END statement. This 
then becomes part of the .REL 
file which informs LINK where 
to begin execution (see also 
the END pseudo-op) . 


?Load ing 

Error 

The last file given 
linked and loaded is 
properly formatted LINK 
file. 

to be 
not a 
object 

?Fa tal 

Table 

Collision There is not 

memory to load the 
prog ram ( s) . 

enough 

given 

?Command 

Error 

An unrecognizable LINK 

command 


has been given. Type the 
correct c ommand or re- link. 


?File Not Found A file in the command string 

does not exist as spell ed or 
specified. Check to see if the 
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file resides on the specified 
drive. Often this message 
results if the user forgets to 
specify the drive letter, and 
LINK looks on the current 
dr ive . 


Warnings 

% 2 nd COMMON Larger /XXXXXX/ The first 

definition of COMmon block 
XXXXXX is not the largest. 
COMmons do not have to be the 
same size provided the module 
containing the larger COMmon 
specification is linked first 
so that LINK allocates an 
appropriate number of bytes for 
da ta storage . To pr event this 
error re-order the module 
loading sequence or change the 
COMmon block definitions. 

%Mult. Def. Global YYYYYY More than one 

definition for the global 
( internal) symbol YYYYYY is 
encountered during the loading 
process. This message may 
result if you redefine the LUN 
table of FORTRAN ( $ LUNTB ) and 
then link with FORLIB.REL 
without specifying the /S 
switch. The Linker then loads 
both the redefined version of 
$ LUNTB and the version 
contained in FORLIB. 
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CHAPTER 4: EXAMPLES OF LINKING MODULES 


Following are several examples of the process 
of linking, loading, saving, and executing files. 
The asterisk (*) in the following command lines is 
NOT user-typed; it is the prompt for LINK. 

We would type the following command to load a 
32-byte program called MY PROG into memory and begin 
execution: 

LINK MY PR OG /G 

If the load is successful (no errors) , the Linker 
will respond with the message: 

[1000 1020 16] [BEGIN EXECUTION] 

This program will begin execution at 1000H. If we 
desired to save the program prior to execution, we 
could type instead: 

LINK MYPROG/E 

to which the Linker would respond with: 

[1000 1020 16] 

followed by a return to CDOS and the issue of the 
CDOS prompt. This return to CDOS does not change 
the user area; hence, we could then save the 
program by typing : 

SAVE MYPROG.COM 16 

Since we have named this a .COM file, we can 
execute it directly from CDOS by typing the name 
" MY PROG " . 

Another example would be to link several 
modules together as they are loaded into memo ry . 
Suppose we have the three relocatable modules 
GRAPHX, MAIN, and SUBPLOT. We first type: 
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LINK <CR> 

to which LINK responds with the asterisk. We could 
then type: 

MAIN 

The Linker would look on the current drive for MAIN 
and then return the still-undefined symbols (each 
one followed by an asterisk) and the address at 
which they are referenced: 

INITG* 1 22E 
LINE* 164D 
CURSR* 163E 
STRIN* 1 3 IB 

SUBROT* 147D 
* 


We then link the next module: 

GRAPHX 

and LINK again responds with the undefined symbols 
and the prompt: 

SUBROT* 147D 
* 

Finally, we link the last module: 

SUBROT 

to which link responds with the prompt. We could 
now type /G or /E to run or exit from the program 
as we did in the first example. However, let's 
first generate a map of all the symbols using the 
/M LINK swi tch : 

*/M 

to which the Linker would respond: 
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INITG 122E 
LINE 164D 
CURSR 1 63E 
STRIN 1 3 IB 
SUSRQT 147D 
PAGE 17DF 
DOT 180E 
ANIMT 1558 


Note that this is similar to the map of undefined 
symbols; however, in this case symbols which are 
not used , but have been defined in one of the 
linked programs, are also listed. 

The above example could also have been linked 
directly, and without producing the maps of 

undefined symbols, by typing the command line: 

LINK GRAPHX, SUBPLOT, MAIN/M 

Note also that this command line links them in a 
different order than the first case since all of 

the modules are relocatable. Thus, the map printed 
to the console this time would have a different 
address after each symbol. 

The Linker can also be used to link machine 

language sub routines to programs written fo r and 
compiled with CROMEMCO FORTRAN IV. The assembly 
language subroutine should be assembled with ASMB, 
which forms a .REL file. The form of the link is 

then exactly the same as for the previous example. 
An important note is that LINK has been designed to 
automatically search FORLIB.REL, the FORTRAN 
Library file of subroutines. LINK looks for this 
file on drive A, rather than the current drive. 
The user can force the Linker to look for FORLIB on 
another drive by typing a command like: 

LINK FORTRAN, SUBROT, B:FORLIB/S 

where FORTRAN is the user's compiled FORTRAN 
program. Note the use of the /S switch following 
FORLIB. This tells LINK to load into memory only 
those routines which are actually needed rather 
than the entire Library. It is important to use 
this switch with library files in order to save 
memory space . 
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Finally, note that 
at any time while using 
or loading process, for 
C (“C> . 


the user may return to CD03 
LINK {to abort the linking 
example) by typing Control- 
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CHAPTER 1: INTRODUCTION TO DEBUG 


The CROMEMCO DEBUG program makes it possible 
to test and debug user programs. DEBUG is loaded 
into memory and moved to the highest memory 
available below CDOS. When using a 32K CDOS and 
DEBUG, there is 20K left for the user program. 


LOADING DEBUG 


DEBUG is loaded by typing one of the following 
commands from CDOS. 

DEBUG 

DEBUG filename. ext 

where "filename" is the name of the program to be 
tested, and "ext" is the file extension. In both 
cases, DEBUG is loaded into memory directly below 
CDOS. The CDOS jump Instruction located at 
location 5H is changed to jump to the start of 
DEBUG. This allows locations 6H and 7H to still 
point to the lowest available memory location. 

The second command above is used to load the 
file to be tested into memory. If the extension 
{"ext") is ".HEX", then the file is read as an 
INTEL HEX file. Any other extension is read as an 
absolute binary file, loaded at location 100H. 
Note that DEBUG does not load relocatable files. 
If an extension is ".REL" it will be loaded in as 
if it were binary and will not be executable. 
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CONTROL CHARACTERS 


Control characters 
to help in entering 
characters are the same 


are used in DEBUG and TRACE 
commands. These control 
as CDOS uses. 


Control-C ("C) 
Control-H ("H) 
Control-U ("U) 
Control-X ("X) 
underscore 
RUBout (DEL) 


go back to CDOS 

delete character and backspace on CRT 
delete line 

delete character and echo 

delete character and backspace on CRT 

delete character and backspace on CRT 


During a printing (such as from the DM 
command) the following characters may be used. 

Control-S ( " S ) stop/start printing. If 
printing, this character will 
stop the printing. If already 
stopped, this character will 
resume the printing . 

break (or any other character) will 

abort the printing, prompt, and 
wa i t fo r the next comma nd . 


COMMAND FORMAT 


DEBUG is controlled by one and two character 
commands from the terminal. The format is free- 
form with respect to spaces. Commas may be used in 
place of spaces. In the following, the examples 
all dump memory starting at location 1000H and 
ending at location 1 0PFH . 

DM1000 1 0FF (CR) 

DM 1000S100 (CR) 

D M 1000 1 0FF (CR) 

D M 1000 S 100 (CR) 

DM1000, 10FF (CR) 

DM1000, S100 (CR) 

D M 1000 , 10FF (CR) 
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@ REGISTER 


DEBUG was designed to give flexibility in 
testing relocatable programs. The register is 

used to tell DEBUG where the module you wish to 
debug is located. This address can be found from 
the map generated by the linking loader "LINK". To 
change the " register, type (CR)" on the 

console. The computer will then type "@-xxxx " 
(where xxxx is the current value of the register). 
The computer will then wait for a new address. If 
a CR only is typed, the register remains unchanged. 
If an address and a CR is typed, then the register 
will contain the new address. The register may 

now be used as part of an address. The following 
example demonstrates its use. 

G/g @A3 1000 

This is an example of the go command. Break 
points will be set at the beginning of the current 
module, relative location ASH in the current 
module, and at location 1000 H. This feature allows 
you to test a module without having to calculate 
absolute addresses. 


ADDRESS EXPRESSIONS 


For additional ease in specifying addresses an 
expression can be used. Within these expressions, 
addition, subtraction, the register, and the 
"$" may be used. The "$" is the current location 
of the program counter (P register) . If many 
modules are being tested, addition can be used to 
specify relative addresses. 

G/2321+A3 

The preceding example would set a break point 
at relative location A3H if the module is located 
at 2321H . 
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SWATH OPERATOR 


There are two ways to specify the address 
range of many commands. The first is to simply 
list the beginning and end addresses (and where 
appropriate, the destination address). For 
example, the first command below programs the range 
0 through 13FFH into PROMs starting at location 
E400H. The second command displays the contents of 
memory between addresses E400H and E402H. 

P0 13FF E400 

DME400 E402 

Another way to do the same thing is to use the 
Swath operator, M S", to specify the width of the 
address range, rather than state the end address 
expl ic i tl y . 

P0 S1400 E400 

DM E400S3 


ERRORS 


Any errors mad e during entering of a command 
may be corrected by typing Control-U (~U) to abort 
the line or by backspacing and correcting the line. 
If a CR has already been entered and DEBUG detects 
an error, the line will not be accepted and a "?“ 
will be printed. Re-enter the line with the 
incorrect data corrected. 
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CHAPTER 2: DEBUG COMMANDS 


DEBUG and TRACE commands are described in 
detail below. The operator must wait for the 
prompt character before entering the command. 


A - Assemble into memory 

This command allows in-line assembly language 
to be assembled into memory. The command takes the 
following format. 

A beginn ing-addr (CR) 

The user is prompted with the absolute 
address, followed by the relative address. DEBUG 
reads from the console the assembler mnemonics and 
assembles the instruction into memory. The 
mnemonics for the various Z-80 instructions can be 
found in the Z-80 CPU TECHNICAL MANUAL published by 
Mostek and Zilog. If there was no error in the 
instruction, it is stored in memory and the user is 
prompted for the next instruction. The rules for 
address expressions apply to the addresses in the 
assembler mnemonics. In the following example the 
" register contains 1234H. 

A@4 0 

1274 0040' ADD B 

1275 0041 ' CALL @93 

1278 0044' JP 1032+95 

127B 0047' . 

The A command terminates when the first blank line 
or a line starting with a is entered from the 

console. If there is an error in the input line, 
it will not be accepted, a "?" will be printed and 
the console will be prompted with the addresses 
aga in . 
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DM - DISPLAY MEMORY 

The contents of memory are displayed in 
hexadecimal form. Each line of the display is 
preceded by the address of the first byte and 
followed by the ASCII representation of the 
hexadecimal bytes. An example follows: 

DM100, S30 

0100 40 41 42 43 44 45 46 47-48 49 4A 4B 4C 4D 4E 4F @ ABCDEFGH I JKLMNO 

0110 50 51 52 53 54 55 56 57-58 59 5A 30 31 32 33 34 PQRSTUVWXY2 01 234 

0120 35 36 37 38 39 00 00 00-00 00 00 00 00 00 '00 00 56789 

The formats of this command are as follows. 

DM (CR) 

DM beg innig-addr (CR) 

DM beg inn i ng-addr ending-addr (CR) 

DM beg inn ing-add r S swath-width (CR) 

DM, ending-addr (CR) 

DM S swath-width (CR) 

The first format displays memory from the 
CURRENT display address, initially 100H, and 
continues for 8 lines. The second format displays 
from the beginning address and continues for 8 
lines. The third format displays from the 

beginning address to the ending address. The 
fourth format displays from the beginning address 
for a length specified by the swath-width. The 
fifth format displays from the CURRENT display 

address to the ending address. The sixth format 
displays from the CURRENT display address for a 
length specified by the swath-width. 

If an "X" is included after the "DM", the 
relative addresses are also printed. In the 
following example assume that the register 

conta ins 1 00H . 

DMX100 , S30 

0100 0000’ 40 41 42 43 44 45 46 47-48 49 4A 4B 4C 4D 4E 4F @ ABCDEFGH I JKLMNO 

0110 0010’ 50 51 52 53 54 55 56 57-58 59 5A 30 31 32 33 34 PQRSTU VWXYZ0 1234 

0120 0020’ 35 36 37 38 39 00 00 00-00 00 00 00 00 00 00 00 56789 
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DR - DISPLAY REGISTERS 

When DEBUG is re-entered from a break point, 
the user registers are saved. The registers may be 
displayed at any time by typing the following 
command . 

-DR (CR) 

SZHVNCE A=00 BC=0 0 00 DE = 0000 HL=0000 S = 0100 P=0100 0100' LD E , A 
SZHVNC A 1 =0 0 B 1 - 0 000 D 1 =0 000 H'=0000 X=0000 Y=0000 1=00 

The letters "SZH VW C" on the first row 
represent the flags, while on the second row they 
represent the prime flags. If the flag is on, it 
is printed, if the flag is off, a space is printed. 

If only the carry and zero flag are set then " Z C M 
would be printed. The flags are described below. 

S - Sign flag, S=1 if the MSB of the result 

is one, i.e., the result is negative. 

2- Zero flag, Z = 1 if the result of an 

operation is zero. 

H - Half-carry flag, H=1 if the add operation 

produced a carry into the 4th bit of the 
accumulator or a subtract operation 
produced a borrow from the 4th bit of the 
accumul a to r . 

V - Parity or overflow flag. This flag is 

affected by arithmetic and logical 
operations. If an overflow occurs during 
an arithmetic operation, the flag is set 
to one. After a logical operation, the 
flag is set to 1 if the result of the 
operation has even parity. 

N - Add/subtract flag, N=1 if the last 

operation was a subtraction. 

C - Carry flag, C=1 if the operation produced 

a carry. 

The E flag on the first line is the state of 
the interrupt enabled flip-flop (IFF). If 
interrupts are enabled, the "E" is printed, 
otherwise a space is printed. 
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The A register is printed next, followed by 
the BC, DE, and HL register pairs and the stack 
pointer. The program counter value is then printed 
in both absolute and relative. The opcode pointed 
to by the prog ram counter is then displayed as an 
instruction . 

On the second line, the prime registers are 
displayed, F' (prime flags). A', BC', DE 1 , and HL'. 
The IX, I Y, and I (interrrupt page) registers are 
printed next. If the disassembled opcode includes 
an address, the relative value of this address is 
printed as the last thing on the line. 


-DR (CR) 

S H NCE A=00 BC=00 00 DE=0000 HL=0000 S=0000 P=1234 0010' CALL 
SZ NC A ' =00 B ' =0000 D 1 =0000 H 1 =0000 X=0000 Y=0000 1=00 


E - EXAMINE INPUT PORT 

The data port is read and displayed as a 
hexadecimal number. The format of the command is: 

E data-port (CR) 

In the following example the data port 3 is 
read and displayed on the console. 

-E3 (CR) 

23 


EJ - EJECT DISK 


The format of the command follows. 

EJ d 

Where d is the disk number (A, B, C, D) . If the 
designated disk is a CROMEMCO DUAL DISK SYSTEM 
model PFD, with the eject option, the diskette in 
the disk drive will eject. 


F - SPECIFY FILE NAME 

This command allows the operator to insert 
filenames in the two default FCBs (at 5CH and 6CH) 
and the command line into the default buffer (at 


1334 
( 0110 ' ) 
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80H} . The example below loads FILE1.COM into the 
first FCB and FILE2.COM into the second FCB. The 
complete line is also loaded into the default 
buffer . 

-FFILE1.COM FILE2.COM 0PTI0N1 0PTI0N2 

This command can be used with the "R" command to 
read in disk files. 


G - GO 

The GO command has the following format. 

G(starting-addr)/(breakpoint-l) (breakpoint-2) . . . (breakpoint- 5) 

Each of the addresses is optional. If the starting 
address is omitted, then the contents of the 
program counter is used. The registers are loaded 
from the user registers (these are the values 
displayed with the DR command). Execution begins 
with the starting address or the contents of the 
program counter. If break points were specified, 
an RST 30H is inserted at the break point addresses 
and a jump instruction is placed at location 30H. 

When a breakpoint is executed, control is returned 
to DEBUG , and all of the user registers are saved 
(the registers may then be displayed with the DR 
command). ALL breakpoints are then removed from 
the user prog ram . The program counter is d i spl ayed 
after the breakpoint. Note the following about 
breakpo ints : 

(a) Breakpo ints can only be set in prog rams 

residing in RAM . This is because an RST 30H is 

inserted at each break point location. (The 
original contents of these locations are saved so 

that they can be restored after a break point is 

executed . } 

(b) Up to 5 break points can be set. If an 

attempt is made to enter more than 5 break points, 
the command will not be accepted. 

(c) When a break point is used, a jump 

instruction is stored at location 30H. Therefore 
locations 30H, 31H, and 32H are not ava liable to a 

user program. 

The GO command has an additional feature that 
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is very helpful in debugging a program. A count is 
allowed for each break-point. This count is 
entered after the break-point and enclosed in 
parentheses. This count is the number of times the 
program reaches this address before control is 
returned to DEBUG. A count of one says to break 
the next time the address is reached. In the 
example below execution begins at location 100H and 
will break when address 109H is reached for the 
second time or when 123H is reached for the first 
t ime . 


-G 1 00/109 ( 2 ) 123 

Note that 123 and 123(1) means the same thing. 
Also note that the count is a hexadecimal number. 
Therefore 123(F) means to break after the address 
has been executed for the 15th time. 


H - HEXADECIMAL ARITHMETIC 

Hexadecimal addition and subtraction may be 
performed by this command. The first number to be 
printed is the sum of the two input numbers. The 
second number to be printed is the difference 
between the first number and the second number. In 
the example following, the first number is 1234 + 
321, and the second number is 1234 -321. 

-H1234, 321 

1555 0F1 3 


L - LIST IN ASSEMBLER MNEMONICS 

The list command is used to list the contents 
of memory in assembly language mnemonics. The 
formats for this command are. 

L (CR) 

L s ta r ting-add r (CR) 

L star t i ng-add r ending-addr (CR) 

L starting-addf S swath-width (CR) 

L, ending-addr (CR) 

L S swath-width (CR) 

The first format lists 16 lines of 
disassembled code starting from the current list 
address. The second format lists 16 lines from the 
starting address. The third format lists from the 
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starting address to the ending address. The fourth 
format lists from the starting address for a length 
specified by the swath width. The fifth format 
lists from the current list address to the ending 
address. The sixth format lists from the current 
address for a length specified by the swath 
address . 

The first address of the disassembly is the 
absolute address. The second address is the 
relative address. If the disassembled instruction 
contains an address, the absolute address is 
printed in the instruction in hexadecimal and the 
relative address is printed to the right of the 
disassembled line. In the example that follows, 
the register contains 2800H. 


-L@8 

00 812 



3000 

0800 ' 

ADD B 


3001 

0801 ' 

CALL 3200 

( 0A00 ' ) 

3004 

0804 1 

CALL 3243 

( 0A43 ' ) 

3007 

0807 ' 

CALL 3333 

{ 0B 33 1 ) 

3 0 0A 

080A 1 

LD A, B 


300B 

080B 1 

OR C 


300C 

080C ' 

JR Z , 3000 

(0800 1 ) 

300F 

080F ' 

INC HL 


3010 

081 0 1 

INC DE 


3011 

0811 ' 

INC BC 


3012 

0812 1 

LD A, H 



M - MOVE MEMORY 

The formats of this command follow. 

M source-addr source-end dest inati on-add r 

M source-addr S swath-width dest ina t io n-add r 

The first format moves the contents of memory 
beginning with the source address and ending with 
the source-end to the destination address. The 
second format uses the swath width to determine the 
length of the move. 

The move is verified to insure that all bytes 
were moved correctly. If an overlapping move was 
made, errors will be reported. The error reporting 
can be terminated by typing any character. 

The move command can be used to fill a block 
of memory with a constant. In the following 
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example, a zero has been entered into location 100H 
using the SM command. The following command will 
move zeros from location 100H through 108H. 


-Ml 00 S7 101 

Care should be taken not 
TRACE or CDOS. 



to move memory over DEBUG, 


0 - OUTPUT TO DATA PORT 

This command outputs data to a data port. The 
following is the command format. 

0 data-byte port-number {CR) 


P - PROGRAM PROMS 

This command allows programming of PROMs. The 
following are the command formats. 

P source-addr source-end destination-addr 

P source-addr S swath-width destination-addr 

The first format programs PROMs starting with the 
source address and ending with the source-end into 
PROMs beginning at the destination address. The 
second format determines the length from the swath 
width . 

If the length of the source is not a multiple 
of 400H or if the destination does not begin at a 
400 H boundary, DEBUG will reject the command. 
(Multiples of 400H end in '000', '400', ’800 1 , and 

’C00 1 . ) 

Any number of 2708 or 2704 PROMs can be 
programmed in the execution of one command as long 
as there are enough BYTE SAVERS to contain them . 
Each PROM is verified with its source after all are 
programmed and any discrepancies are printed out. 
If no discrepancies are found , a prompt is printed 
and the next command may be entered . 

Software can be loaded into a PROM in as small 
increments as you desire, provided it is added to 
previously unused areas of the PROM. This is done 
by first using the Move command, "M" , to transfer 
the contents of the PROM to RAM, adding the new 
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software to an area of RAM which corresponds to the 
unused portion of the PROM and finally using the 
Program command, "P" , to reprogram the PROM with 


the result, 
programmed , 
over again. 

1 , a 0 over 

1 


Athough the entire PROM must always be 
it never hurts to rewrite the same data 
In general, a 1 may be written over a 
either a 1 or a 0, but the only way to 


to 


change 0’s 
appropriate UV light. 
II manual for details.) 


is to erase the PROM with 
(See the Cromemco BYTESAVER 


R - READ DISK FILE 

This command allows the operator to read a 
disk file. The "R" command is used with the "F" 
command. The "F" command is used to specify the 
filename, and the "R" command reads in the file. 
If the file has an extension of ".HEX", then the 
file is an INTEL HEX file and will be read into 
memory. Any other file is considered to be a 
binary file and will be read directly into memory 
beginning at location 100H. The format of the "R" 
commmands is: 


R 

R d i spl acemen t 



The 

first 

f o rm a t 

reads the file 

with 

n 0 

displacement- The seco 

nd format 

reads 

the f 

il e 

wi th 

a d i 

spl aceme 

nt. If 

the input 

file i 

s in HEX, 

then 

the 

displacement is 

added to 

the add 

r esses 

in 

the 

file 

to dete 

!rmlne the add res, 

ses at 

which 

to 

store the 

file. 

If the 

file is a 

binary 

file, 

it 

will 

be stored at 

the dis 

pi acemen t 

+ 100H. 




When 

the "R" 

c ommand 

is executed, DEBUG pr i 

nt s 


either a " ? " if there is an error (file not found, 
checksum error, or file attempting to read above 
highest available memory location) or with the 
following message if there is no error: 

NEXT = xxxx 

where xxxx is the address of the next available 
memory location past the end of the file. 
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SM - SUBSTITUTE MEMORY 

This command is used to substitute memory. 
The format of the command follows. 

SM star t i ng-add r 

DEBUG prints the absolute address, followed by the 
relative address, followed by the contents of the 
memory byte. One of the following may then be 
entered . 

{a) data-byte value. The data byte value 
is stored at the address of the 
prompt. The address is then 
incremented by 1 and displayed on the 
next line. 

(b) string enclosed in quotes. The string 
is stored beginning at the address of 
the prompt. The address is then 
incremented past the string and 
displayed on the next line. 

(c) Any number of (a) and ( b) above can be 
entered on one line. The address is 
then incremented past the bytes that 
were stored and the new address is 
displayed on the next line. 

(d) A minus sign does not store a 
byte. The address will be decremented 
to the previous address. The minus 
sign can be used to "back up" to a 
previous location in case an error has 
been made. 

(e) (CR) only. If no entry is made on the 
line, the memory byte remains 
unchanged. The address is incremented 
by 1 and displayed on the next line. 

(f) period. A period ends the input mode 
and returns to the command level . 

In the example that follows, assume that the 
register contains the value 2800H. 

— SM@ 1 0 0 
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2900 0100' 32 0 

2901 0101’ 17 00 

2902 0102' 31 'THIS IS AN ASCII STRING' 
2919 0119’ 7 A 1 AAAA 1 00123456789 

2928 0128’ 22 

2929 0129' 29 
292 A 01 2A ' 87 - 
2929 0129' 29 . 


Sr - SUBSTITUTE REGISTER 

The Sr command allows the user registers to be 
altered. The letter "r" stands for the register 
which is to be changed. The section SUMMARY OF 
REGISTER NAMES gives a summary of the names that 
can be substituted. When substituting the F and F 1 
flags, enter the command SF or SF' . DEBUG will 
then print the flags that are set and wait for the 
operator to enter the names of the registers that 
are to be set. If the flags are NOT entered, the 
flags are reset. In the following example, the 
"SZHC" flags are set. After the example is 
executed the "ZC" flags are set. The lower case 
letters are entered by the operator. 

-sf 

SZH C zc 

When sust i tut i ng a one byte register, a one 
byte value is accepted. When substituting a two 
byte register, a two byte value is accepted. If no 
value is entered, or if an error occurs, the value 
of the register remains unchanged. In the 
following example, the A register is changed to 
contain 41 H. 

-sa 

A-9 8 41 
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T - TRACE 

The format of trace is: 

T (CR) 

T number-of- 1 ines (CR) 

The first format traces the program through one 
instruction. The second format traces the program 
through "number-of-lines" instructions. After 
every instruction traced, the values of the user 
registers are printed in the same format as the 
"DR" command. 

You can trace only through RAM. The trace 
command places a break point after the instruction, 
loads the registers and executes the instruction. 
The break point is then executed and the registers 
are resaved. The registers are printed, and the 
next instruction is executed unless the count has 
reached zero, in which case a prompt is printed and 
you may enter the next command. 

To abort the trace, hit any key on the 
console. A prompt will be printed and you may 
enter the next command . 


TN - TRACE WITH NO PRINTING 

The "TN" command is the same as the "T" 
command with the exception that after every 
instruction is traced, the registers are not 
printed. Only the last traced instruction is 
printed. 


V - VERIFY MEMORY 

Verify that the block of memory between souce 
address and source end contain the same value as 
the block beginning at destination address. The 
addresses and contents are printed for each 
discrepancy found. The following is the format of 
this command . 

V source-addr source-end dest i nat i on-add r 

V source-addr S swath-width dest ina t io n-add r 
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This command works by reading bytes from the source 
and destination and comparing them. If a 
discrepancy is found, the memory is read again for 
print-out. Thus, it can happen that a discrepancy 
is printed-out with the source and the destination 
contents indicated to be the same. This is caused 
by a defective memory element. 

A discrepancy is printed in the following 
order, source address, source contents, destination 
contents, destination address. In the example that 
follows, memory locations 1003 H and 100 8H are 
defective. 

-V 0 S 30 1000 
0003 32 12 1003 
0008 7A 5A 1008 


135 



yaoDnaaa wvusoad oowswohd 



CROMEMCO PROGRAM DEBUGGER 


CHAPTER 3: SUMMARY OF DEBUG COMMANDS 


The following is an alphabetical list of the 
DEBUG commands. 

Command Description 

A Assemble into memory 

DM Display Memory 

DR Display Register 

E Examine input port 

EJ Eject disk 

F specify disk File name 

G Go 

H Hexadecimal arithmetic 

L List in assembler mnemonics 

M Move memory 

0 Output to data port 

P Program PROMs 

R Read disk file 

SIM Substitute Memory 

Sr Substitute register 

(r=A, B, D, H, S, P, 

A' , B 1 , D\ H 1 , X, Y, I) 

T Trace 

TN Trace with No print 

V Verify memory 


137 



CROMEMCO PROGRAM DEBUGGER 


SUMMARY OF REGISTER NAMES 

The following register names are printed by 
the DM command and should be used with the Sr 
command . 

Reg i ster Deer i pt ion 

F Flags, the following flags may be changed. 

S -Sign flag 

Z -_Zero flag 

H -Half carry flag 

V -parity/oVerflow flag 
N -subtractioN flag 
C -Carry flag 

The interrupt enable flag ("E") may also be changed. 

F' The F' flags are the same as the " F" flags. 

(note that the "E" flag may not be changed here.) 

A accumulator 

A ' prime accumul a to r 

B BC register pair 

B ' BC' register pair 

D DE register pair 

D 1 DE' register pair 

H HL register pair 

H' HL' register pair 

S Stack pointer 

P Program counter 

X IX register 

Y IY register 

I Interrupt page register 
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CHAPTER 1: INTRODUCTION TO CDOS SYSTEM CALLS 


This section of the manual descibes the use of 
CDOS system calls. CDOS handles disk files, 
performs device input and output, and contains a 
number of useful subroutines. 


Memo ry A1 location 


CDOS resides in high memory. It reserves 
memory below 10 0 H for its own use. The user is 

left all memory from 100H to the beginning of CDOS 
( see below) . 

A program with the extent ".COM" can be loaded 
and executed by merely typing the program name. 

The program must have its origin at 100H because 
that is where CDOS loads and executes it. (Note 
that when saving files that have been linked using 
the CROMEMCO Linker, they can be LINKed anywhere 
using the /P option. This is because LINK 
automatically puts the correct jump instruction at 
100H.) After it is loaded, the program can use any 

memory at all. Note however that if it alters the 

CDOS areas, it will have no way of communicating 

with the disk or returning to CDOS. (CDOS would 
have to be reloaded by resetting the computer.) 

CDOS places a jump instruction at bytes 0, 1 

and 2. If a jump is made to location 0, the CDOS 
warm start, control will be returned with the 

prompt for the current drive (eg, "A.") . Command 
lines may then be entered from the console 

keyboard. CDOS places another jump instruction at 
locations 5, 6 and 7. The normal way to make 

system requests of CDOS (those described below) is 
to call location 5. The address stored at 
locations 6 and 7 is the address of the beginning 

of CDOS and thus marks the upper limit of user 
memory. 
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The following address map describes the memory 
area from 0 to 0FFH. All addresses are in hex. 


0 ... 2 

3 

4 

5. . .7 

8. . .40 

40. . . 5B 
5C . . . 6B 
6C. . . 7B 

70 . . . 7F 
8 0 . . . FF 


CDOS re-entry 
I/O byte 
reserved 

system request call 
interrupt vectors 
rese rved 

default File Control Block 1 (FCB-1) 

default File Control Block 2 (FCB-2) 

reserved 

default command-line buffer 


When a .COM program is run by typing the 
program name on the console, the default command- 
line buffer and default file control blocks are 
used as follows. FCB-1 will contain the first 
filename, if any, typed after the program name. 
FCB-2 will contain the second filename, if any. 
The default buffer will contain the entire command 
line following the program name. For example, if 
this command line is typed: 


PROG FILE1.Z80 FILE2.COM 


CDOS will place "FILE1Z80" in FCB-1, "FILE2C0M" in 
FCB-2, " FILE1.Z80 FILE2.COM" in the command-line 
buffer, and load and execute PROG.COM at 100H. 
Note that the second FCB starts before the end of 
the first FCB. Before using FCB-1, FCB-2 should be 
moved. If it is not moved, part of FCB-2 will be 
destroyed . 

The command line which is placed in the 
default buffer can be used to send more than two 
filenames to a program, or to start execution of a 
program with various options specified. For the 
following command line: 

PROG FILE1.Z8 0 FILE2.COM OPT ION 1 0PTI0N2 

the string of ASCII characters " FILE1.Z80 
FILE2.COM 0PTI0N1 0PTI0N2" will be stored beginning 
at location 81H. The byte at location 80H will 
contain the length of the string. The byte 
following the string will contain a null (00). 
PROG.COM can then look at the command line stored 
in the default buffer to determine which options 
were specified. 
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When a program is loaded, the disk buffer is 
set to 80H, which is the default command buffer. 
If the disk Is then read to or written from, this 
buffer will be altered. The program must either 
reset the disk buffer to another area or move the 
command line before accessing the disk, if it is 
desired to save the command line. 
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CHAPTER 2i DEVICE I/O 


LIST OF CDOS SYSTEM CALLS 


CDOS has a set of system calls for device 
input and output. ALL input and output should be 
done through these calls. This allows user 
programs to be independant of physical devices. If 
a change needs to be made in a device driver, it 
has only to be done once in the system drivers. 
This chapter gives a detailed description of the 
CDOS system calls. They are roughly divided into 
three sections: the first section covers device 

I/O, where all devices are included except disk 
drives. The next section covers the system calls 
used to access disk files (disk I/O, opening and 
closing files, etc.). The last section covers 
several useful additional calls. To use one of 
these routines the C register must be set to the 
function number given below with the title of each 
instruction. The other registers are set-up as 
that function requires (for example the E or DE 
registers usually contain the parameter passed) , 
and a " CALL 5" instruction is executed. [Remembe r 
that CDOS initializes location 5 with a jump 
instruction. This is done so that the location of 
CDOS in memory is transparent to a user prog ram. A 
user program using the CDOS system functions does 
therefore not need to do a CALL to a particular 
address in CDOS.] For a complete summary of the 
CDOS system calls, refer to Chapter 3. The system 
calls given below are in numerical order in each of 
the three sections. 


CDOS DEVICE FUNCTION CALLS 


These system calls involve device I/O with all 
devices except disk drives. The number given 
preceding each CDOS function is the number which 
should be loaded into the C register prior to the 
"CALL 5". The number is given first in hex and 
then in decimal in parentheses. 
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1 - READ CONSOLE {with echo) 

This call is used to retrieve one byte from 
the console. The byte will be returned in the A 
register. CDOS does not return to the user program 
until a character is read and echoed back to the 
console. The parity bit is set to 0. Note that a 
Control-Z ["Z) character is usually considered an 
end of file mark. 


2 - WRITE CONSOLE 

This call is used to write one ASCII character 
to the console. The character is placed in the E 
register before the call. CDOS will wait until the 
console is ready to receive the character and then 
print it. 

After Control-P ("P) is typed all subsequent 
characters are sent to both the console and the 
printer, until a second Control-P is typed {thus 
Control-P acts as a toggle switch). Control-W also 
causes subsequent characters to be sent to both the 
console and the printer, and Control-T causes them 
to be sent only to the console again. Control-W 
and Control-T are usually edited into a file so 
that when that file is typed out on the console, it 
can stop and start the printer at the appropriate 
places . 

Control-I is the tab control. It is converted 
to spaces so that the cursor is positioned at one 
of the standard tab stops, 1, 9, 17, 25, 33, 41,... 
However, the tab is still stored internally in a 
file as the single ASCII character, 09H. 


3 - READ READER 

This call will read one character from the 
paper tape reader. All 8 bits are read. The 
character will be returned in the A register. If 
it is the end-of-file character {Control-Z), the 
ZERO flag is set. 
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4 - WRITE PUNCH 

This call will punch one character on the 
paper tape punch. All 8 bits are punched. The 
character is placed in the E register before the 
call. CDOS will wait until the punch is ready to 
receive the character. 


5 - WRITE LIST 

This call will print a character on the 
printer. Before the call, the character to be 
printed is placed in the E-register. Tabs are not 
expanded. CDOS will wait for the printer to accept 
the character before it returns. 


7 - GET I/O BYTE 

For extra I/O devices, an "IOBYTE" has been 
provided. This byte is not currently used by CDOS, 
but it is provided for the user's programs. This 
function call returns the "IOBYTE" in the A 
register. The format of the byte is: 

BIT :7:6:5:4:3:2:1:0 

: PRN : PUNCH : READER : CONSOLE 

Thus up to eight consoles can be designated, four 
each of paper-tape punch and reader, and one 
printer. 


8 - SET I/O BYTE 

This call allows the user program to set the 
"IOBYTE". The E register contains the byte prior 
to the call. See above for the format of the byte. 


9 - PRINT BUFFER 

This call will print a string of ASCII 
characters which has been terminated with the 
character. The DE register pair is set up with the 
address of the beginning of the string before the 
call is made to CDOS. If the printer toggle is on, 
the message will also be sent to the printer. 
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10 { 0AH) - INPUT BUFFERED LINE 

This call will read an input line from the 
console. The DE register must be pointing to an 
available buffer before the call is made to CDOS. 
The first byte of the buffer must contain the 
maximum length of the buffer. On return from this 
call the second byte of the buffer will contain the 
actual length entered. The line that is input will 
be stored beginning at the third byte. If the 
buffer is not full, the byte at the end of the line 
will contain a zero. 


When the line is being entered, the following 
characters will have a special meaning: 


Control-C ( "C) 
Control-E ( "E } 


Control-P (~P) 


Con t rol-R (~R) 
Control-U (~U) 

Co nt rol-X ( "X ) 

RUBout 


Abort. Warm boot back .to CDOS. 

Physical CR-LF. The line is 
not terminated and nothing is 
entered into the buffer. This 
character is used to enter a 
line longer than can be printed 
on the console. 

Toggle printer/console link. 
When this character is first 
typed, the link is toggled ON. 
All characters will then be 
sent to the console and the 
printer. The next time the 
character is typed, the toggle 
will be turne'd off. All 
characters will then be sent to 
the console only. 

Repeat what has been typed so 
far on the line. 

Delete the entered line and go 
back to beginning of buffer for 
new line. 

Delete the previous character 
and echo the deleted character 
(used for hard-copy terminals). 

Delete the previous character 
and back up the cur so r (used 
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for CRT terminals). 
DEL Same as RUBout . 

Underscore Same as RUBout. 

Backspace ( "' H ) Same as RUBout. 


11 (0BH } - TEST CONSOLE READY 

The console is tested to see if a character 
has been typed. If a character has been typed, 
0FFH is returned in the A register. If no 
character has been typed, 0 is returned in the A 
register. 


128 (80H) - READ CONSOLE (without echo) 

This call is the same as "READ CONSOLE (with 
echo)" except that it does not echo the character 
after it is read. The byte is returned in the A 
reg i ster . 


142 (8 EH) - SET CURSOR ADDRESS 

This call will set the cursor at the specified 
address. This command will only work when the 
console is a CRT with cursor addressing. The D 
register is set up with the column address (1 
through 80 for most CRT's) and the E register is 
set up with the row address (1 through 24 for most 
CRT’ s) . 
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CDOS DISK FUNCTION CALLS 


CDOS divides the disk into regions called 
files. Files are referenced through file control 
blocks ( FCBs ) . FCBs are 33 bytes long and have the 
following format, where each of the numbers below 
stands for one byte: 


FCBDK 

Disk descriptor 

0 

(0=current disk, l=drive-A, 

2=B , 3=C , 4=D) 

FCBFN 

File name 

1. . .8 

(right-filled with blanks) 

FCBFT 

File type (extension) 

9. . .11 

(right-filled with blanks) 

FCBEX 

File extent 

12 

(initially 0; is incremented 
by one in every new 
extent of 16 Kbytes) 


Reserved 

13. . . 14 


FCBRC 

Record count 

15 

(total number of 128-byte 
sectors or records) 

FCBMP 

Cluster allocation map 

16. . .31 

(allocated clusters 2 
throug h 240 ) 

FCBNR 

Next record 

32 

(next record to be read or 
written; has the value 

0 through 127) 


It should be noted that directory entries on 
the disk consist of 3 2- byte FCBs. The last byte, 
FCBNR, which points to the next record, is omitted. 


12 (0CH) - DESELECT CURRENT DISK 

The current disk is deselected. The CDOS disk 
driver can be changed to perform any desired 
function at this time to deselect the disk. 
Currently the driver outputs a 0 to port 34H when 
this function is selected. 
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13 (0DH ) - RESET CDOS AND SELECT DRIVE A 

CDOS is initialized, all disks are logged-off, 
and drive A is selected as the current drive. The 
other disks will be logged-on again as soon as they 
are accessed. 


14 (0 EH) - SELECT DISK DRIVE 

The disk drive number in the E register is 
selected as the current disk. The drive number in 
the E register is 0 for drive A, 1 for drive B, 2 
for drive C, or 3 for drive D. 


15 ( 0FH) - OPEN DISK FILE 

The FCB pointed to by the DE register pair is 
opened to allow reading or writing to the file 
whose name is specified in the FCB . The A reg ister 
returns with -1 (0FFH or 255D) if the file is not 
found, or the directory block number if the file is 
found. Block numbers start at 0 and there is one 
block number for every four directory entries. The 
HL register pair returns pointing to the directory 
entry in memory. 


16 (10H) - CLOSE FILE 

The FCB pointed to by the DE register pair is 
closed and the disk directory is updated. The file 
described by the FCB must have been previously 
opened or created; if it has not been, an 
unpredictable directory entry will be written to 
the disk. A file to which bytes have just been 
written MUST be closed using this function or the 
entire last extent will be unable to be read. 


17 (11H) - SEARCH DIRECTORY 

The directory is searched for the first 
occurrence of the file specified in the FCB pointed 
to by the DE register pair. ASCII "?" (3FH) in 

the FCB matches any character. The block number 
(see description of directory block numbers in 0FH 
-Open Disk File, above) is returned in the A 
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register if found; if the file is not found, -1 
{0FFH or 255D) is returned in A. HL is returned 
pointing to the directory entry in memo ry * An 
important point to note about this call and the one 
following (12H) is that they will get the directory 
entry whether it has been erased or not; i.e., 
these calls do not check to see if a file has been 
erased. Files are erased by placing a 0E5H in the 
first byte (FCBDK); the rest of the FCB is left 
unchanged . 


18 (12H) - FIND NEXT DIRECTORY ENTRY 

This call is the same as 11H (17) above except 
that it finds the NEXT occurrence of the filename 
in the directory. This may be either the next 
extent of a file occupying more than one extent, or 
another filename if the match-character, was 
used in the FCB. This call is made after function 
17 and no other disk system call can be made 
be tween these calls. 


19 (13H) - DELETE FILE 

The file specified by the FCB pointed to by 
the DE register pair is deleted from the disk 
directory. ASCII 11 ? " in the FCB matches any 
character. The number of directory entries deleted 
is returned in the A register. 


20 (14H) - READ NEXT RECORD 

The DE register pair points to a successfully 
OPENED FCB . The next record (128 bytes) is read 
into the current disk buffer. The FCBNR in the FCB 
i s inc remen ted to read the next record. One of the 
following codes is returned in the A register: 

0 - read completed 

1 - end of file 

2 - read attempted on unwritten cluster 

(random access file only) 
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21 (15H) - WRITE NEXT RECORD 

The DE register pair points to a successfully 
OPENED FCB. The next record (128 bytes) is written 
into the file from the current disk buffer. The 
FCBNR in the FCB is incremented to be ready to 
write the next record. One of the following codes 
is returned in the A register: 

0 - write completed 

1 - extent error (attempted to close an unopened extent) 

2 - out of disk space (limited to 81K - small, 241K - large) 
-1 - (0FFH or 255D) out of directory space (limited to 

64 extents) 


22 { 1 6H) - CREATE FILE 

The file specified in the FCB pointed to by 
the DE register pair is created on the disk. The A 
register is returned containing the block number of 
the directory entry (see 0 FH -Open Disk File), or - 
1 ( 0FFH or 255) if no more directory space is 

ava il abl e . 


23 (17H) - RENAME FILE 

This call will rename a disk file. The DE 
register pair points to the FCB to be renamed. The 
old file name and file type are in the first 16 
bytes and the new file name and file type are in 
the second 16 bytes of the FCB. ASCII "?" in the 
FCB will match with any character. The A register 
returns containing the number of directory entries 
renamed . 


24 (18H) - DISK LOG-IN VECTOR 

The A register is returned specifying the 
disks that are logged in. Each bit represents one 
disk drive logged in. If the bit is a one, then it 
is logged in; else it is off-line. The least 
significant bit is the A drive, next most 
significant (Bit 1) is drive B, etc. Since there 
would be no more than four drives, the upper four 
bits are 0's. 
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25 { 19H ) - CURRENT DISK 

The number of the current disk drive is 
returned in the A register. 0 = drive A, 1 = drive 
B, 2 = drive C, 3 = drive D. 


26 ( 1 AH) - SET DISK BUFFER 

The buffer pointed to by the DE register pair 
is used for disk I/O. When a program is loaded, 
the disk buffer is initially located at 80H. 


27 (1BH ) - DISK CLUSTER ALLOCATION MAP 

The BC register pair returns pointing to a bit 
map that corresponds to the allocated clusters on 
the disk. The DE register pair returns containing 
the capacity of the current disk in number of 
clusters. The A register returns containing the 
number of records or sectors per cluster (8). This 
system call is used by "STAT" . 


131 (8 3H) - READ LOGICAL BLOCK 

This system call will read a logical block 
from the disk without any attention to the files it 
may contain (i.e., no FCB is specified). A block 
is defined to be one sector or record of 128 bytes. 
When this function is called, the DE register pair 
sho uld contain the block number and the B register 
should contain the disk number (0 for current 
drive, 1-4 for A-D) . The high bit of the B 
register contains a 1 for an interleaved and a 0 
for a non-interleaved read. Interleaved means the 
block which is read is found in the order CDOS 
stores it (every fifth sector for small disks and 
every sixth sector for large disks). Non- 
interleaved means the block which is read is found 
in sequential order, the order it is physically 
stored on the disk. The A register is returned 
with the status of the read according to the 
following : 

0 -OK 

1 -I/O error 

2 -illegal request 
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3 “-illegal block 

An example will help to illustrate these 
points* CDOS makes use of 716 sectors on the small 
floppy disks* Therefore, the block numbers which 
could legally be loaded into the DE register are 0 
through 715 decimal, or 0 through 2CBH* Suppose 
that DE is loaded with the value 2 and the B 
register with 0 (current disk, non-interleaved 
read)* Thus, since the sectors are numbered 
beginning with 1, sector 3 would be read into 
memory in the disk buffer (located at 80H if it has 
not been changed}* The same read with the B 
register loaded with 80H (current disk, interleaved 
read) would read sector 0BH (the third sector when 
they are read every fifth one). 


132 (3 4H } - WRITE LOGICAL BLOCK 

This system call will write a logical block or 
sector to the disk without any attention to the 
file there (no FOB is specified). The registers 
are set up and returned in the same way as they 
were for the Read Logical Block system call above. 


134 (86H) - FORMAT NAME TO FCB 

This system call will build a File Control 
Block. The HL register pair points to the start of 
the input line* The DE register points to the 
place in memory wh er e the FCB is to be built. The 
input line is of the format: 

d : f il ename • ex t 

where d stands for one of A-D, the filename is up 
to 8 letters with a 3-letter extension. The FCB is 
then built from this input line, converting lower 
case to upper case- The input line is terminated 
by an ASCII u / n or any character less than 21H 
(such as a space or carriage return) * 

On return the HL register pair points to the 
terminator that ended the build operation* The DE 
register pair points to the start of the new FCB* 
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135 (87H) - UPDATE DIRECTORY ENTRY 

The last disk I/O function called must have 
been function 17 or 18, Search Directory or Find 
Next Entry. The DE register pair points to the FCB 
used in the function call 17 or 18. The directory 
entry is then updated on the disk; this means that 
the entry is written back to the disk without the 
user having to specify a block. The user merely 
specifies a filename when calling 17 or 18. This 
is useful if it is desired to change a directory 
entry and write it back to the disk. 


139 { 8BH) - HOME DISK 

The disk drive specified in the B register (0 
for current drive and 1-4 for drives A-D) is sent a 
command to "home" the head. The disk drive head 
will return to track 0. 


140 ( 8CH) - EJECT DISK 

This call will eject the disk whose number is 
given in the E register (0 for current drive and 1- 
4 for drives A-D, respectively), only if the disk 
drive is a CROMEMCO Dual Disk Drive System, Model 
PFD with the eject option. Otherwise, the call 
will have no effect. 


ADDITIONAL SYSTEM CALLS 


Several additional CDOS system calls have been 
added for the programmer's convenience. These 
calls are explained in this section. 


0 - ABORT 

This call will abort the current program and 
return control to CDOS. This call has the same 
effect as jumping to location 0. 
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129 { 8 1 H ) - GET USER REGISTER POINTER 

This call is provided for expansion of CDOS to 
a multiprogramming system. The BC register pair 
returns pointing to the user register pointers. 


130 (82H) - SET USER CONTROL-C ABORT 

When Control-C {"C) is typed, the system 
usually aborts and returns control to CDOS. This 
call allows the programmer to assign an address to 
which to jump when Control-C is typed (i.e., users 
can assign their own function to Control-C). The 
address is given in the DE register pair. Note 
that if DE contains a zero, the system abort is 
reset. Jumping to location 0 at any time still 
causes a return to CDOS, also with the Control-C 
being restored to its original function. 


136 (88H) - LINK TO PROGRAM 

This enables one command program to call 
another. The default command-line buffer and 
default FCBs for the new program must be set up 
prior to this call if that program expects to be 
able to use them . The DE r eg i ster pa i r should 
contain the address of the FCB of the new program 
{which must have an extension of ".COM"). If the 
new program is NOT found, the A register returns 
containing -1 (0FFH or 255); also in this case the 
first 80H bytes (from 100H to 17FH) will be 
destroyed because this is used in reading the 
directory. Otherwise, execution begins at 100H and 
no return is made to the original program. 


137 (89H) - MULTIPLY 

This system call provides a 16-bit multiply. 
The HL and DE register pairs contain the two 16-bit 
factors, and the answer is returned in register DE 
{i.e., DE = DE*HL) . 
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138 {8AH) - DIVIDE 

This system call provides a 16-bit divide. 
The HL register pair should contain the dividend , 
and the DE register pair, the divisor. The 
quotient is returned in HL, and the remainder in DE 
(ie, HL = HL/DE with DE = remainder). DE contains 
the remainder . 


141 (SDH ) - GET VERSION NUMBER 

This call will return the version-number of 
CDOS in the B register and the release- number in 
the C register. 
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CHAPTER 3: SUMMARY OF CDOS FUNCTION CALLS 


Following is a summary table listing all the system calls 
in Chapter 2 along with their entry and return parameters. The 
are listed in numerical order, i.e., by order of the number 
loaded into the C register to achieve the desired function. 


described 
f unctions 
which is 


NUMBER 

FUNCTION 

ENTRY PARAMETERS 

RETURN PARAMETERS 

0 


ABORT 

none 

none 

1 


READ CONSOLE 
( with echo) 

none 

A = character 

2 


WRITE CONSOLE 

E = character 

none 

3 


READ READER 

none 

A = character 

Z flag set = end of file 

4 


WRITE PUNCH 

E = character 

none 

5 


WRITE LIST 

E = character 

none 

7 


GET I/O BYTE 

none 

A = I/O byte 

8 


SET I/O BYTE 

E = I/O byte 

none 

9 


PRINT BUFFER 

DE = buffer address 

none 

10 

( 0AH) 

INPUT BUFFERED 
LINE 

DE = buffer address 

none 

11 

( 0BH) 

TEST CONSOLE 
READY 

none 

A = 0FFH (-1) if ready 

A = 0 if not ready 

12 

{ 0CH) 

DESELECT 

CURRENT DISK 

none 

none 

13 

( 0DH ) 

RESET CDOS AND 
SELECT DRIVE A 

none 

none 

14 

( 0EH } 

SELECT DISK 

E = disk drive 

none 

15 

( 0FH ) 

OPEN DISK FILE 

DE = FCB address 

A - directory block 

A = 0FFH if not found 

16 

(10H) 

CLOSE FILE 

DE = FCB address 

none 

17 

{ 1 1 H ) 

SEARCH 

DIRECTORY 

DE = FCB add ress 

A = directory block 

A = 0FFH if not found 

18 

(12H) 

FIND NEXT ENTRY 

DE = FCB address 

A = directory block 

A = 0FFH if not found 

19 

(13H) 

DELETE FILE 

DE = FCB address 

A = number of entries 
deleted 

20 

(14H) 

READ NEXT 

RECORD 

DE = FCB address 

A = 0 if ok 

A = 1 if end of file 

A = 2 if tried to read 
unwritten records 

21 

(15H) 

WRITE NEXT 

RECORD 

DE = FCB address 

A = 0 if ok 

A = 1 if extent error 

A = 2 if out of disk 
space 

A = -1 { 0FFH) if out 

of directory space 
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NUMBER 


FUNCTION 


ENTRY PARAMETERS 


RETURN PARAMETERS 


22 

(16H) 

CREATE FILE 

DE = FCB address 

A = directory block 

23 

(17H) 

RENAME FILE 

DE = FCB address 

A = number of entries 
renamed 

24 

(18H) 

DISK LOG-IN 
VECTOR 

none 

A = those disks 

logged- in 

25 

(19H) 

CURRENT DISK 

none 

A = disk number 

26 

C 1AH ) 

SET DISK BUFFER 

DE = buffer address 

none 

27 

(1BH) 

DISK CLUSTER 
ALLOCATION MAP 

none 

BC = address of bitmap 

DE = number of c 
A = sectors/cluster 

128 

(80H) 

READ CONSOLE 
(with no echo) 

none 

A = character 

129 

(S1H ) 

GET USER 
REGISTER 

POINTER 

none 

BC = pointer to user 
register 
po inters 

130 

(82H) 

SET USER 
CONTROL-C 

ABORT 

DE = address 

none 

131 

( 8 3 H } 

READ LOGICAL 
BLOCK 

DE = block number 

B = disk number 

B top bi t = 1 if 
interleaved 

A = 0 if ok 

A ® 1 if I/O error 

A = 2 if illegal request 
A = 3 if illegal block 

132 

(84H) 

WRITE LOGICAL 
BLOCK 

DE = block number 

B = disk number 

B top bi t = 1 if 
interleaved 

A = 0 if ok 

A = 1 if I/O error 

A = 2 if illegal request 
A = 3 if illegal block 

134 

(86H) 

FORMAT NAME 

TO FCB 

HL = address of 
string 

DE = FCB address 

HL = address of 
terminator 

DE ~ FCB add ress 

135 

( 8 7 H ) 

UPDATE 

DIRECTORY ENTRY 

DE = FCB address 

none 

136 

{ 8 8H ) 

LINK TO PROGRAM 

DE = FCB address 

A = -1 if error, else 
execute at 100H 

137 

(89H) 

MULTIPLY 

DE = factor 1 

HL = factor 2 

DE = product 

138 

( 8AH ) 

DIVI DE 

HL = dividend 

DE = divisor 

HL = quotient 

DE = remainder 

139 

{ 8BH ) 

HOME DISK 

B = disk number 

none 

140 

(8CH) 

EJECT DISK 

E = disk number 

none 

141 

( 8DH ) 

GET VERSION 

none 

B = version-number 

C = release-number 

142 

( 8EH ) 

SET CURSOR 
ADDRESS 

D = column address 

E = row address 

none 
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CROMEMCO ASSEMBLER LIBRARY ROUTINES 


CHAPTER 1: ROUTINES AVAILABLE IN ASMLIB 


The library file " ASMLIB. REL" has been 
provided for your use in assembly language 
programming. There are three types of routines 
(decimal conversion, hexadecimal conversion, and 
character I/O). An example of how to add these 
routines to your program follows. 

LINK PROG ,ASMLIB/S/G 

This example will load a program called "PROG" and 
then load only the routines in "ASMLIB" that are 
required. See Part II on LINK for more 
info rma t ion . 


DECIMAL CONVERSION 


ADEC - DECIMAL TO BINARY CONVERSION 

This routine will convert a decimal string to 
a binary number. The following example will 
illustrate how to use this routine. 

LD BC, STRING ; point to ASCII string 

CALL ADEC ; convert to binary 


The routine will return with the HL register pair 
containing the 16-bit binary number and the BC 
register pair pointing to the first non- digit. 


BINDF, BINDB, BINDS, BIND - 
CONVERT BINARY TO DECIMAL 

These routines will convert a binary number 
into a decimal string. The routine "BINDF" will 
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zero fill, "BINDB" will fill with spaces, "BINDS 11 
will suppress printing of leading zeros, and "BIND" 
will fill with the character in the A register. In 
the following example leading zeros will be printed 


LD 

HL, STRING 

; store ASCII string here 

LD 

BC, (BINARY) 

fthis is binary number 

LD 

A, 1 + ' 

;fill character 

CALL 

BIND 

;convert to ASCII string 


Six bytes must be reserved for the string, unless 
"BINDS" is used, in which case this routine will 
use only the number of bytes that are not leading 
zeros. The decimal numbers returned are in the 
range 0 through +32767 {0H - 7FFFH) and -32768 

through -1 (8000H - FFFFH) . 


HEXADECIMAL CONVERSION 


AHEX - ASCII TO HEX CONVERSION 

This routine will convert a hexadec imal string 
(which must be terminated by an ' H ' ) to a binary 
number. The calling sequence is 

LD BC, STRING ;point to ASCII string 

CALL AHEX jconvert to binary 


The routine will return with the HL register pair 
containing the binary number and the BC register 
pair pointing to the first nonhexadecimal digit. 


BINH4 - BINARY TO 4 HEX DIGITS 

This routine will convert the binary number in 
the BC register pair to 4 ASCII digits. The 
calling sequence is 

LD BC, (NUMBER) 

LD HL, STRING 

CALL BINH4 
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BINH2 - BINARY TO 2 HEX DIGITS 

This routine will store 2 ASCII digits. The 
calling sequence is 

LD A, (NUMBER) ;get binary number 

LD HL, STRING ;store ASCII string here 

CALL BINH2 


BINH1 - BINARY TO 1 HEX DIGIT 

This routine will store 1 ASCII digit. The 
calling sequence is 

LD A, (DIGIT) ;get binary digit (lower 4 bits of A) 

LD HL, STRING ;store digit here 

CALL BINH1 


CHARACTER I/O ROUTINES 


Providing character I/O which is device 
independent adds considerable power to a program. 
These routines allow opening a file by symbolic 
name (disk or device) and then calling the same 
routines for I/O. There are routines for both 
ASCII and BINARY data. The binary calls pass 8 
bits of data. The ASCII calls pass only printable 
characters plus carriage return, line feed, and 
tab. All other characters are passed as two 
characters (an up arrow and the corresponding 
printable character; e.g., Control-B would be 
printed as ,[ "B"). Devices are referenced by using 
the following symbolic names; all others are 
considered disk files. 

RDR: [#] -reader (0. .4) 

PUN: [#] -punch (0. .4) 

LST : [ # ] -printer (0..1) 

PRT:[#] -printer (0..1) 

CON:[#] -console ( 0 . . 7 ) 

DUM: -dummy 
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The option number is set into the "IOBYTE" to 
select device units. The symbolic name "DUM:" is 
used to throw away output, or as end of file. 

An extended FCB (XFCB) is used which includes 
character pointers. When the XFCB is initialized, 
the number of buffers are specified {each is 128 


bytes) . 

Only disk 

files use the 

buffers . 

The format of the 

XFCB follows 

• 

name 

posi tion 

length 

description 

ZCNT 

0 

1 

byte count (0..127 or 255) 

Z FCB 

2. .34 

33 

CDOS file control block (FCB) 

ZBPTR 

3 5. .36 

2 

buffer pointer (1st buffer) 

ZBCUR 

37 

1 

current buffer 

ZNBUF 

38 

1 

number of buffers 

ZFBUF 

39 

1 

full number of buffers 


40 total length 


The byte count indicates a non-disk device if 
it contains 255. ZFLG will then contain the system 
call for that device. The following are the flags. 


RDR : 3 

PUN: 4 

LST : 5 

PRT: 5 

CON: 1 

DUM: 0 


The initial format of an XFCB should be: 


DEFB 0 

DBFS 34 

DEFW buffer address,0 

DEFB number of buffers 


FNAME - SET UP XFCB 


This routine sets up an XFCB from an FCB. If 
the routine is called with the A register equal to 
0, then the extension in the FCB is used. If the A 
register is not equal to 0, then the A, B, and C 
registers contain the extension that is to be used. 
The example below will set up an XFCB from the 
system FCB at location 5CH with an implied 
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extension of 
files only. 

" . PRN" . This 

routine 

LD 

HL, 5CH 

,-po int 

LD 

DE , XFCB 1 

; po i n t 

LD 

A, ' P 1 

; " . PRN 

LD 

BC, 'RN' 


CALL 

FNAME 

; build 


is for disk 


to system FCB 
to XFCB 
" extension 

XFCB 


XDISK - SET UP SPECIAL XFCB 

This routine will modify an XFCB using a 
letter in the A register. If the A register 
contains A through W, this is considered to be a 
disk identifier. If the A register contains "X" , 
the XFCB is converted to use the console. If it 
contains a "Y", the XFCB is converted to use the 
list device. If it contains a "Z", then the XFCB 
is converted to use the dummy driver. This routine 
allows the decoding of parameters such as the 
assembler uses for its files. In the following 
example the XFCB is converted to use the console. 


LD 

DE , XFCB 

; point 

to 

the XFCB 

LD 

A, 1 X ' 

;make i 

t 

the console 

CALL 

XDISK 

; conver 

t 

XFCB 


ZNEW - OPEN NEW XFCB 

This routine will delete any old file with the 
same name and then create and open a new file. If 
there is an error the ZERO flag is set and the HL 
r eg i ste r pa i r po ints to an error message. In the 
following example a new file is created. 


LD 

DE , XFCB 

;point to XFCB 

CALL 

ZNEW 

;create a new file 

CALL 

Z , ZIOER 

;print error and abort 


ZOPN - OPEN OLD XFCB 

This routine will open an existing file. if 
there is an error the ZERO flag is set and the HL 
register pair points to an error me s sag e . In the 
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following example an old file is 

opened 

* 

LD 

DE, XFCB 

; po i n t 

to XFCB 

CALL 

ZOPN 

; open 

the file 

CALL 

2 , ZIOER 

; pr int 

error and abort 


ZCLOS - CLOSE XFCB 


This routine will close 

a f il 

e . In the 

following exampl 

e a file is closed . 


LD 

DE , XFCB 

; point 

to XFCB 

CALL 

ZCLOS 

; cl ose 

the file 

CALL 

Z, ZIOER 

; pr int 

error and abort 


PCHAR - PUT CHARACTER (BINARY) 

This routine is used to output binary 
characters. In the following example a character 
is output. 


LD 

DE, XFCB 

; po int to XFCB 


LD 

C, (HL) 

;get character to 

output 

CALL 

PCHAR 

; output character 


CALL 

Z, ZIOER 

; pr in t error and 

abort 


PUTC - PUT CHARACTER 

(ASCII) 

This r o 

utine is used 

to output ASCII 

cha r acte rs to 

a disk file or a 

device such as the 

console, a printer, etc. In the following example 

a character is 

output . 


LD 

DE , XFCB 

; po int to XFCB 

LD 

C t (HL) 

;get character to output 

CALL 

PUTC 

;output character 

CALL 

Z, ZIOER 

;print error and abort 


GCHAR - GET A CHARACTER 

This routine is used to input characters from 
a disk file or a device. In the following example, 
a character is returned in the A register. 
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LD 

DE , XFCB 

;point to XFCB 

CALL 

GCHAR 

;get a character 

CP 

1 AH 

; Q , end of file 

JP 

Z ,EOF 

;yes, end of file 


When an unwritten random record is read, it is 
treated as an end of file. 


ZIOER - PRINT FILE ERROR MESSAGE 

This routine is the standard error routine. 
When an error occurs in one of the file handling 
routines, the HL register pair points to the error 
message, the DE register pair points to the XFCB, 
and the ZERO flag is set. This allows the 
instruction "CALL Z, ZIOER" to follow a disk 
handling routine. In the following example, a 
character is written. If there is an error, it 
will be printed and control will be passed to CDOS. 


LD 

DE , XFCB 

;po int 

to XFCb 

LD 

C, (HL) 

;get a 

character 

CALL 

PUTC 

; output 

character 

CALL 

Z , ZIOER 

; print 

error and abort 


PFNAM - GET FILE NAME FOR PRINTING 

This routine will extract the file name from 

the XFCB and form a printable string. The string 
will be in the following format: 

d : f il ename . ex t 

where d: is an optional disk number (A-D), 

filename is the name of the user file (1 to 8 

characters), and ext is the filename extension (0 
to 3 characters). The string is terminated by a 

byte equal to zero. The length of the string is 
returned in the A register. In the following 

example a string is formed from the XFCB. 


LD 

DE , XFCB 

; point 

to XFCB 

LD 

HL, BFLINE 

jstore 

string here 

CALL 

PFNAM 

; fo rm 

string 

CALL 

PRNT 

; pr int 

the file name 
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PRNT - PRINT A LINE 

This routine will print a string which ends 
with either a zero-byte or a carriage return. If a 
carriage return is found, the carriage return and a 
line feed is output. In the following example the 
String "THIS IS A STRING" is output. 


LD 

DE , XFCB ;set up 

for device 

LD 

HL, STRING jpoint 

to string 

CALL 

PRNT ;print 

the string 

STRING: DEFB 

'THIS IS A STRING' ,0 



ABORT - ABORT USER PROGRAM 

This routine will print a message and then 
abort to CDOS. The format of the message is the 
same as in the previous example. In the following 
example the message "*** END OF JOB ***" is output 
to the console and control is returned to CDOS. 


LD 

HL, STRING 

; point to string 

CALL 

ABORT 

jabort program 

STRING: DEFB 

'*** END OF JOB 

***' ,13 
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CHAPTER 2: AN EXAMPLE 


The program " EXAMPLE . Z80 " has been included as 
an example. To run this example use the batch file 
" EXAMPLE . CMD" . The first line of "the example is 
typed by the user. The rest of the example is 
typed by the computer. 

B.@ EXAMPLE 

BATCH VERSION 00.02 

B.ASMB EXAMPLE. AAX 

CROMEMCO CDOS Z80 ASSEMBLER version 02.02 
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CROMEMCO CDOS Z80 ASSEMBLER version 02,02 PAGE 0001 

*** EXAMPLE *** 




0002 

f 





0003 

; T H I S PROGRAM 

WILL INPUT 

FROM ONE 



0004 

; DISK FILE OR 

DEVICE 




0005 

; AND OUTPUT TO 

ONE DISK 

FILE OR DEVICE 



000 6 

t 





0007 

; TO CALL THIS 

PROGRAM TYPE 



0008 

; "EXAMPLE filenaml.ext f i 1 enam2 . ex t" where 



0009 

; " f i 1 enaml * ex t 

" IS THE OUTPUT FILE/DEVICE and 



0010 

; 11 f il enam2 . ext 

" IS THE INPUT FILE/DEVICE 



0011 

i 





0012 

NAME 

EXAMPL 




0013 

EXT 

FNAME 

; SET UP XFCB 



0014 

EXT 

ZNEW 

; OPEN NEW XFCB 



0015 

EXT 

ZOPN 

; OPEN OLD XFCB 



0016 

EXT 

ZCLQS 

; CLOSE XFCB 



0017 

EXT 

ZIOER 

; ERROR ROUTINE 



0018 

EXT 

ABORT 

; END PROGRAM 



0019 

EXT 

GCHAR 

; GET A CHARACTER 



0020 

EXT 

PUTC 

; PUT A CHARACTER 



0021 






0022 

; START OF PROGRAM 




0023 

f 



0000 ' 

3A5D00 

0024 

START: LD 

A, (SDH) 

; 1ST BYTE OF FILENAME 

0003 ' 

FE20 

0025 

CP 

f r 

; Q , BLANK FILE NAME 

0005 ' 

CA6500 ' 

0026 

JP 

Z r ERROUT 

; Y E S , ERROR 

0008 1 

97 

0027 

SUB 

A 

; USE EXT FROM FCB 

0009 ' 

215C00 

0028 

LD 

HL, 5CH 

; POINT TO 1ST FCB 

000C ' 

117F00 1 

0029 

LD 

DE , OXFCB 

; POINT TO OUTPUT XFCB 

0 0 0 F 1 

CD0000# 

0030 

CALL 

FNAME 

; BU I LD XFCB 

0012 ' 

CD0000# 

0031 

CALL 

ZNEW 

; CREATE A NEW FILE 

0015' 

CC0000# 

0032 

CALL 

Z , ZIOER 

; ERROR 



0033 

r 



0018 1 

3A6D00 

0034 

LD 

A, (6DH) 

; 1ST BYTE OF FILENAME 

0 0 IB ' 

FE20 

0035 

CP 

* i 

;Q, BLANK FILE NAME 

0 0 1 D ' 

CA6500 ' 

0036 

JP 

Z , ERROUT 

; YES , ERROR 

0020 ' 

97 

0037 

SUB 

A 

; USE EXT FROM FCB 

0021 ' 

216C00 

0038 

LD 

HL, 6CH 

; POINT TO 2ND FCB 

0024 ’ 

11A700 ' 

0039 

LD 

DE, IXFCB 

; POINT TO INPUT XFCB 

0027' 

CD1000# 

0040 

CALL 

FNAME 

; BU I LD XFCB 

002A ' 

CD0000# 

0041 

CALL 

ZOPN 

; OPEN OLD XFCB 

002D ' 

CC1600# 

0042 

CALL 

Z , ZIOER 

; ERROR 



0043 

/ 



0030 ' 

11A700 1 

0044 

LOOP; LD 

DE, IXFCB 

; POINT TO INPUT XFCB 

0033 ’ 

CD0000# 

0 04 5 

CALL 

GCHAR 

; GET A CHARACTER 

0036 ' 

FE1A 

0046 

CP 

1AH 

} Q , END OF FILE 

0038 ' 

280C 

0047 

JR 

Z ,EOF 

; YES 

003A 1 

117F00 ' 

0048 

LD 

DE, OXFCB 

; POINT TO OUTPUT FCB 

00 3D 1 

4F 

0049 

LD 

C , A 

; GET CHARACTER 

0 0 3 E ' 

CD0000# 

0050 

CALL 

PUTC 

; PUT ASCII CHARACTER 

0041 ' 

CC2E00# 

00 51 

CALL 

Z , ZIOER 

; ERROR 

0 0 4 4' 

1 8 E A 

0052 

JR 

LOOP 

; G E T NEXT CHARACTER 
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0053 ; 



0046 ' 

117F00 ' 

0054 EOF: 

LD 

DE , OXFCB 

0049 ' 

CD0000# 

0055 

CALL 

ZCLOS 

0 04C ' 

215200 ' 

0056 

LD 

HL, EOF MSG 

0 04F * 

CD0000# 

0057 

CALL 

ABORT 



0058 ; 




, -CLOSE OUTPUT XFCB 

; POINT TO EOF MESSAGE 
; ABORT PROGRAM 



CROMEMCO ASSEMBLER LIBRARY ROUTINES 

CROMEMCO CDOS Z80 ASSEMBLER version 02.02 PAGE 0002 

*** EXAMPLE *** 

0052’ 2A2A2A20 0059 EOFMSG: DEFB '*** END OF JOB ***’,13 

4 54E4420 
4F46204A 
4F42202A 
2A2A0D 




0060 

0061 

0062 

•ERROR ROUTINE 

f 

FOR MISSING 

FILES 

0065 ' 

216B00 ' 

0063 

ERROUT: LD 

HL, ERRMSG 

; POINT TO MESSAGE 

0068 1 

CD5000# 

0064 

0065 

CALL 

r 

ABORT 


006B 1 

53504543 

0066 

ERRMSG : DEFB 

'SPECIFICATION ERROR 1 , 13 


49464943 
4154494F 
4 E2 04552 
524F520D 


0067 ; 

0068 ; OUTPUT XFCB 

0069 ; 


00 7F ' 

00 

0070 OXFCB : 

DEFB 

0 

0080’ 

(0022) 

0071 

DEFS 

34 

00A2 ' 

CF00 ’ 

0000 

0072 

DEFW 

OBUFF , 0 

0 0 A6 1 

04 

0073 

DEFB 

4 


0074 ; 

0075 ; INPUT XFCB 

0076 ; 


0 0A7 ' 

00 

0077 

IXFCB : 

DEFB 

0 


00A8 ' 

(0022) 

0078 


DEFS 

34 


00CA 1 

CF02 ' 

0079 


DEFW 

IBUFF, 0 



0000 






0 0CE ' 

04 

0080 


DEFB 

4 




0081 

# 




0 0CF 1 

(0200) 

0082 

OBUFF: 

DEFS 

80H*4 

; OUTPUT BUFFERS 

0 2CF ' 

(0200) 

0083 

IBUFF : 

DEFS 

8 0H* 4 

; INPUT BUFFERS 



0084 

r 




0 4CF ' 

( 000 0 1 ) 

0085 


END 

START 


Errors 

0 





Program Length 

0 4CF (1231) 





end of assembly 


B . LINK EXAMPLE ,ASMLIB/S/E 
[1000 18B6 24] 

B . SAVE EXAMPLE.COM 24 

B. 
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The program "EXAMPLE.COM" is now ready to be 
executed. To use the program type in the name of 
the program followed by an output file and an input 
file. Fo r example : 

B. EXAMPLE NEWFILE.Z80 EXAMPLE. Z80 

This example will copy the file " EXAMPLE. Z80" to 
the file "NEWFILE. Z80" . 

Device names may also be used . The following 
example will type the file " EXAMPLE. Z80" on the 
console . 

B. EXAMPLE CON: EXAMPLE. Z80 
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PROCEDURE FOR CREATING A NEW LUN TABLE FOR FORTRAN 


There have been a number of requests among our 
customers for information on how to change the 
driver dispatch table (LUN Table) to accommodate 
other I/O drivers with CROMEMCO FORTRAN IV. The 
purpose of this section is to explain the method 
for doing this. The present LUN Table is located 
in the FORTRAN Library file, FORLIB.REL, under the 
name: $LUNTB. The Linker automatically searches 

FORLIB when linking FORTRAN programs to satisfy any 
undefined symbols. LINK then loads these needed 
routines into memory. However, if the LUN Table 
were defined PRIOR to the search of FORLIB, the 
Linker would not load $LUNTB from FORLIB. This is 
done by first composing the new LUN Table giving it 
the same name ($LUNTB), then assembling it using 
ASMB , and finally linking it prior to the link of 
FORLIB. This procedure is demonstrated below. 
However, first here is a duplicate of the LUN Table 
which is pr esentl y used in CROMEMCO FORTRAN : 



ENTRY 

$LUNTB 


EXT 

$DRV3 , LPTDRV, DSKDRV 

SLUNTB: 

DB 

0BH 

ONE: 

DW 

$DRV3 

TWO: 

DW 

L PT DRV 

THREE: 

DW 

$DRV3 

FOUR: 

DW 

$ DR V 3 

FIVE : 

DW 

$DRV3 

SIX: 

DW 

DSKDRV 

SEVEN: 

DW 

DSKDRV 

EIGHT: 

DW 

DSKDRV 

NINE : 

DW 

DSKDRV 

TEN: 

DW 

END 

DSKDRV 


Note the use of the ENTRY statement to define 
the module. The symbols $DRV3, LPTDRV , and DSKDRV 
stand for the console driver, line-printer driver, 
and disk driver modules, respectively. The labels 
ONE through TEN are provided for convenient 
reference; they mark the driver-address which 
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stands for each of the LUNs 1 through 10. As can 
be seen from the above, LUNs 1 and 3-5 are 
presently assigned to the console, LUN 2 is 
assigned to the printer, and LUNs 6-10 are assigned 
to disk files. (See FORTRAN IV Instruction Manual, 
Appendix B and page 15 for more information on 
Logical Unit Numbers.) Also note in the above that 
the first byte of the module (DB 0BH) must be one 
more than the maximum LUN (in this case 10). 
Hence, more LUNs could be defined simply by adding 
DW statements and by changing this first byte. 

The present LUNs can be changed simply by 
rearranging the driver addresses in each DW 
statement above. (LUN 3 should be preserved as the 
console driver, however, as that is the one used by 
the system to print out error messages.) Users may 
also write their own drivers in 2-80 assembly code, 
assemble them with ASMB, and link them with the new 
$ LUNTB . To illustrate these ideas here is a sample 
altered LUN Table: 



ENTRY 

$ LUNTB 


EXT 

$DRV3 , LPTDRV, DSKDRV, SPTDRV 

$ LUNTB : 

DB 

21 

ONE : 

DW 

$DRV3 

TWO: 

DW 

$DRV3 

THREE: 

DW 

$DRV3 

FOUR: 

DW 

L PT DRV 

FIVE : 

DW 

LPT DRV 

SIX: 

DW 

SPTDRV 

SEVEN: 

DW 

SPTDRV 

EIGHT: 

DW 

DSKDRV 

NINE: 

DW 

DSKDRV 

TEN: 

DW 

DSKDRV 

ELEVN : 

DW 

DSKDRV 

TWELV : 

DW 

DSKDRV 

THIRTN: 

DW 

DSKDRV 

FOURTN: 

DW 

DSKDRV 

FIFTN : 

DW 

DSKDRV 

SIXTN: 

DW 

DSKDRV 

SEVNTN: 

DW 

DSKDRV 

EIGHTN: 

DW 

DSKDRV 

NINETN: 

DW 

DSKDRV 

TWENTY: 

DW 

DSKDRV 


END 


this ex am pi e the 

user has added an EXTernal 


declaration for a serial line-printer, SPTDRV. The 
LUN assignments have also been changed as follows: 
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LUNs 1 through 3 are assign ed to the console, 4 and 
5 are assigned to the parallel-port printer, 6 and 
7 are assigned to the serial-port printer, 8 
through 10 remain assigned to disk files, and LUNs 
11 through 20 have also been assigned to disk 
files . 


The driver for the serial printer should be of 
the format: 

ENTRY SPTDRV 

START: 


END 


The LUN file which has been created can now be 
assembled using ASMB simply by typing: 

ASMB LUNTBNEW 

where LUNTBNEW. Z80 is the name of this file on the 
disk. The source file for the added driver 
(SPTDRIVR. Z80 ) must also be assembled; ASMB will 
create .REL files for both these modules. These 
two files can finally be linked to the FORTRAN by 
typing : 

LINK FORPROG, LUNTBNEW, SPTDRIVR 

where FORPROG is the user's pr evi ously-c ompi 1 ed 
FORTRAN IV program. LINK will automatically search 
FORLIB, but will ignore the $LUNTB file there 
because LUNTBNEW was linked first. Note that the 
ENTRY statement for LUNTBNEW. Z80 must have the same 
name as the original module ($LUNTB) . 
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USING A SMB AND DEBUG TO PROGRAM PROMS 


The usual method for storing a program into 
PROMs is to first load the program into RAM at a 
different location from the ROM card containing the 
PROMs to be programmed. Then DEBUG (the "P" 
command) is used to actually do the programming. 
However, DEBUG will attempt to load .HEX object 
files at the location which was specified by the 
ORG statement of the original program (or by the 
address specified by the H£X= option in the absence 
of an ORG), unless a loading offset is specified. 
This offset is specified by the following 
procedure : 

(1) Either ORG the source program at the location 
desired for the PROMs to execute or use the 
HEX= option (see above) at assembly time to 
specify the address. 

( 2 ) Assembl e the source using A SMB and the HEX (or 
HEX= ) option to create a .HEX object file. 

(3) Type "DEBUG <CR>" to call the Debugger 
program . 

(4) After receiving the DEBUG prompt (-), type 

F<filename>.HEX 

where filename is the name of your program on 
the disk. 

(5) Then type 

R<displacement> 

where displacement is a hex number from 0 to 
FFFFH which gives the amount of the 
displacement from the location at which the 
.HEX file is ORGed to the address in RAM at 
which it is desired to load the object code 
(displacement =loading address-run address). 
This displacement should give a loading 
address which is in available RAM. The 
addition of the displacement to the source 
address uses no carry and is limited to 16- 


181 



MISCELLANEOUS PROCEDURES 


bits; this means that a displacement can be 
given to "wrap around" FFFFH. (For example, a 
program ORGed at 9200H will be loaded at 200H 
if an "R7000" command is issued because 
92 00H+7000H=1 02 00H, and the "1" is dropped.) 
DEBUG will not allow a program to be loaded 
over the area where DEBUG lies, and will issue 
a question mark (?) instead of the usual 
" NEXT=xxxx" message . 

(6) Finally insert the PROM(s) to be programmed 
and type the command 

P<so urc e-beg in> <source-end> <destination- 
beg i n> 

to complete the process. 

Note that when using this method, the PROM(s) 
need not be located at the same address for 
programming as they will be for execution. The 
following example will help to illustrate the above 
procedure. Suppose we wish to program a 2708 PROM 
with a monitor program to be run at D000H. Suppose 
also that we have a CROMEMCO BYTESAVER board 
currently addressed at E000H. We then insert the 
PROM into the first available slot on the BYTESAVER 
at F800H. We either ORG our monitor source program 
( cal 1 ed MONITOR, Z80) at D000H and assemble it using 
ASMB, or use no ORG statement in the source program 
and use the HEX=D000 option when assembling, both 
of which create a file called MONITOR. HEX on the 
disk. We now enter DEBUG by typing 

DEBUG <CR> 

and load the .HEX file into memory by typing the 
following two commands to the DEBUG prompt: 

FMONITOR. HEX <CR> 

R4000 <CR> 

to which DEBUG will then respond with (assuming the 
MONITOR program occupies 400H bytes exactly): 

NEXT=1 4 00 

which means the object code file has been loaded 
into RAM from 1000H to 13FFH. We can now program 
the PROM at F800H by typing 
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P1000 S400 F80 0 

When the PROM is completely programmed, it may 
be removed from the BYTESAVER and placed in memory 
at D000H, its run address. Note that the PROM 
could have been programmed while residing at D000H 
if desired; that was not done here simply to 
illustrate a few additional points. Also note that 
the swath length for the P command just above must 
be a multiple of 400H bytes; for example the 
command 

PI 000 1400 F800 

will generate an error in DEBUG. The correct 
command is either 


P1000 13FF F80 0 or 
PI 000 S400 F800 

as above. 
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8080 TO Z80 TRANSLATOR 


For those users who presently have . 

their software written in 8080 Code » 3ft ovftv *-■ * 
Translator program has been provided with the 
Assembler package. This program resides on the 
disk under the filename TRANSLAT.COM. The 
Translator program may be used with source code 
only. Its function is to translate the 8080 
mnemonics of the original code into Z80 mnemonics 
(those published by Mostek and Zilog) , and then 
write this translated program back onto a file on 
the disk. The translated program will then be in a 
form such that it can be assembled by the CROMEMCO 
Z80 Assembler (ASMB.COM) . 


Your original source program must have the 
filename extension .ASM to be found by the 
Translator; if it does not have this extension, 
your file should be renamed before translating it. 
TRANSLAT will create an output file having the same 
filename but with the extension .Z80. The original 
source file will be left unchanged on the disk. 
TRANSLAT requires at least an equal amount of disk 
space for the output file as that used by the 
source file. Therefore, be sure that there is 
sufficient space on the disk before calling the 
Translator. For example, if the source file 
requires 9K in 1 extent, the output file will also 
occupy at least 9K in 1 extent (the output file may 
use more disk space because Z80 mnemonics tend to 
have more characters than 8080 mnemonics). The 
Translator gives three error messages having to do 
with disk I/O: 


OUTPUT FILE WRITE ERROR 


This message occurs during the writing of a 
record to the disk because of one of these 
conditions: (1) out of disk space, more than 81K 

for small and more than 241K for large disks; (2) 
out of directory space, more than 64 extents; (3) 
extent error, an attempt to close an unopened 
extent . 


NO SOURCE FILE PRESENT 
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MISCELLANEOUS PROCEDURES 


The source filename was either misspelled or 
the specified disk does not contain a file of that 
name . 


NO DIRECTORY SPACE 


The output file ( . Z 8 0 ) 
because there are already 64 
stored on the disk. Note that 
from the first error. "OUTPUT 
occurs after the file has been o 
write to it. 


cannot be opened 
files or extents 
this is different 
FILE WRITE ERROR" 
pened but during a 


The Translator will translate opcodes ONLY and 
not pseudo-ops. Therefore any pseudo-ops in the 
source which do not match corresponding ASM B 
pseud o-o ps should be changed by the user (using 
EDIT) after translating but prior to assembling the 
.280 source file. The most common of these is the 
"SET" pseudo-op used with a number of 8080 
Assemblers which should be changed to the "DL" 
pseudo-op for use with ASMB. 

TRANSLAT expects certain standard conventions 
in the 8080 source. Rema r ks should be pr eced ed by 
semi-colons (;) somewhere in the line. Labels 

should be followed by colons ( : ) however, if the 
colon is missing, TRANSLAT will insert it in the 
output file. The opcodes which must be used are 
the standard 8080 opcodes published by Intel. 
Also, the opcodes and register names must be given 
in upper case, and registers must be specified by 
their symbol i c names (A, BC, SP, etc.) instead of 
by values assigned to the registers as is used by 
some Assemblers. 

The Translator works by translating 8080 

opcodes which it recognizes, and ignoring 
essentially everything else in a line of code. 
Pseudo-ops or other lines which do not contain 8080 
opcodes are simply written to the output file 
exactly as they appear in the source file. Be 

aware that if the original 8080 source contains 
syntax or spelling errors, the Z80 output file will 
contain these same errors. Therefore, the output 
file may need to be edited following translation to 
correct the errors; this step is not necessary if 
the source file is formatted according to the 

guidelines described here. 
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A 

A - Assemble into memory, 123 
ABORT, 156 

ABORT - ABORT USER PROGRAM, 170 
ABS (Absolute code segment) , 39 
ABSolute, 57 

ADDITIONAL SYSTEM CALLS, 156 
ADDRESS EXPRESSIONS, 121 

ADEC - DECIMAL TO BINARY CONVERSION, 163 
AHEX - ASCII TO HEX CONVERSION, 164 
Alphabetical List of Pseudo-ops, 39 
argument error, 85 

B 

BIND - Convert Binary to Decimal, 163 
BINDB - Convert Binary to Decimal, 163 
BINDF - Convert Binary to Decimal, 163 
BINDS - Convert Binary to Decimal, 163 
BINH1 - BINARY TO 1 HEX DIGIT, 165 
BINH2 - BINARY TO 2 HEX DIGITS, 165 
BINH4 - BINARY TO 4 HEX DIGITS, 164 

C 

CDOS DEVICE FUNCTION CALLS, 145 
CDOS DISK FUNCTION CALLS, 150 
CHARACTER I/O ROUTINES, 165 
Characters and Line Length, 29 
CLOSE FILE, 151 
COM (COMmon code segment), 39 
Command Format, 105, 120 

COMmon, 59 
Cond, 19 

COND (beg in listing Conditional Assemblies), 53 

Conditional Assembly (IF statements), 74 

Constants, 32 

CONTROL CHARACTERS, 120 

CREATE FILE, 153 

Cross Reference Table, 101 

CURRENT DISK, 154 

Current Program Counter - $, 33 

D 

DATA, 61 

DATA (Data code segment) , 39 
DB or DEFB (Define Byte), 39 
DECIMAL CONVERSION, 163 
Defaults, 27 
DELETE PILE, 152 
DESELECT CURRENT DISK, 150 
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DISK CLUSTER ALLOCATION MAP, 154 
DISK LOG-IN VECTOR, 153 
DIVIDE, 158 

divide by zero error, 85 
DL or DEFL {Define Label) , 40 
DM - DISPLAY MEMORY, 124 
DM or DEFM (Define Message) , 41 
DR - DISPLAY REGISTERS, 125 
DS or DEFS (Define Storage), 42 
DW or DEFW (Define Word) , 43 

E 

E (Exit to CDOS ) , 106 

E - EXAMINE INPUT PORT, 126 

EJ - EJECT DISK, 126 

EJECT DISK, 156 

END (End of assembly) , 44 

ENDIF (END of IF definition) , 45 

ENTRY (Entry point for these modules), 45 

EQU (Equate) , 46 

Error Messages Generated During Assembly, 84 

Error Messages Generated Following a Call to ASMB, 81 

ERRORS, 122 

Examples of Macro and Conditional Assembly, 76 

expression error, 86 

Expressions and Ope r a to rs , 3 4 

EXT or EXTRN (these modules External), 47 

F 

F - SPECIFY FILE NAME, 126 

Fatal Errors, 111 

file not found, 86 

FIND NEXT DIRECTORY ENTRY, 152 

FNAME - SET UP XFCB, 166 

FORM (paper Formfeed), 49 

FORMAT NAME TO FCB , 155 

G 

G (Go - start execution) , 107 
G - GO, 127 

GCHAR - GET A CHARACTER, 168 
Gen, 20 

GEN (begin listing Generated Macros), 53 

GET I/O BYTE, 147 

GET USER REGISTER POINTER, 157 

GET VERSION NUMBER, 158 

H 

H - HEXADECIMAL ARITHMETIC, 128 
HEXADECIMAL CONVERSION, 164 
HOME DISK, 156 
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I 

IF (begin Conditional Assembly) , 50 
INCLUDE (Include the given disk file), 50 
INPUT BUFFERED LINE, 148 
invalid option, 83 

L 

L - LIST IN ASSEMBLER MNEMONICS, 128 
label error, 87 
label not allowed, 87 
Limits, 27 

Lines of Listing , 98 
LINK Switches, 106 
LINK TO PROGRAM, 157 

LIST (use following commands to generate Listings) 

List Options, 19 

Listing Columns, 97 

Listing Symbols, 99 

LOADING DEBUG, 119 

M 

M (Map all symbols) , 107 

M - MOVE MEMORY, 129 

MACRO (begin Macro definition), 54 

Macro Assembly (MACRO definition and calls), 65 

MACRO library not found, 83 

Mac ro = <d : f il ename . ex t> , 2 2 

Memory Allocation, 141 

MEND (Macro definition End), 54 

missing label , 87 

multiple definition, 88 

multiple MACRO definition, 88 

MULTIPLY, 157 

N 

NAME (module Name) , 54 
Names (Labels) , 30 
nesting error, 88 
no directory space, 82 
no matching IF, 88 
no matching MACRO, 88 
Nocond, 21 

NOCOND (do Not print Conditional Assemblies) , 53 
Nogen, 21 

NOGEN (do Not print Generated Macros) , 54 
0 

0 - OUTPUT TO DATA PORT, 130 
OFF (turn Off assembly listing) , 52 
ON (turn On assembly listing), 53 
Opcode, 23 
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Opcode Cross Reference Table, 101 

opcode error, 89 

Opcode Mnemonics, 31 

OPEN DISK FILE, 151 

Operands , 32 

Options Specified When Calling ASMB, 19 
ORG (Origin) , 55 
out of memory, 83 

P 

P - PROGRAM PROMS, 130 
Page=<number decimal lines/page>, 23 
Parity, 24 

PCHAR - PUT CHARACTER (BINARY) , 168 

PFNAM - GET FILE NAME FOR PRINTING, 169 

phase error, 89 

PRINT BUFFER, 147 

PRNT - PRINT A LINE, 170 

PUTC - PUT CHARACTER (ASCII) , 168 

R 

R (Reset linker) , 108 

R - READ DISK FILE, 131 

Range, 24 

range error , 89 

READ CONSOLE (with echo), 146 

READ CONSOLE (without echo) , 149 

READ LOGICAL BLOCK, 154 

READ NEXT RECORD, 152 

READ READER, 146 

REGISTER @ , 121 

REL (Relocatable code segment) , 55 

RELoca table, 62 

REM (Remark beginning in column one), 56 
Remarks , 36 
RENAME FILE, 153 

RESET CDOS AND SELECT DRIVE A, 151 
S 

S (Search file) , 108 

SEARCH DIRECTORY, 151 

SELECT DISK DRIVE, 151 

selected disk error, 82 

SET CURSOR ADDRESS, 149 

SET DISK BUFFER, 154 

SET I/O BYTE, 147 

SET USER CONTROL -C ABORT, 157 

SM - SUBSTITUTE MEMORY, 132 

Source Code Segments, 57 

source file not found, 82 

Sr - SUBSTITUTE REGISTER, 133 
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Summary of Defaults and Limits, 27 

SUMMARY OF REGISTER NAMES, 138 

SWATH OPERATER, 122 

Symbol or Symb , 24 

Symbol Table, 100 

syntax error, 90 

T 

T - TRACE, 134 

Tables Following the Listing, 100 
TEST CONSOLE READY, 149 

TITLE (Title to be printed at top of each page), 56 
TN - TRACE WITH NO PRINTING, 134 
too many COMmons, 90 

Top=<no. dec. lines before top> , 25 

U 

U {list all Undefined globals) , 108 
undefined symbol , 91 
UPDATE DIRECTORY ENTRY, 156 
Upper and Lower Case, 29 

V 

V - VERIFY MEMORY, 134 
value error , 91 

W 

Warnings, 112 

Wid th=<number decimal columns>, 25 
WRITE CONSOLE, 146 

write error, file - <f il enane .ext> , 82 

WRITE LIST, 147 

WRITE LOGICAL BLOCK, 155 

WRITE NEXT RECORD, 153 

WRITE PUNCH, 147 

X 

XDISK - SET UP SPECIAL XFCB, 167 
Xref, 26 

Z 

ZCLOS - CLOSE XFCB , 168 

ZIOER - PRINT FILE ERROR MESSAGE, 169 

ZNEW - OPEN NEW XFCB, 167 

ZOPN - OPEN OLD XFCB, 167 



